Build and preview the website

Build the website locally to preview guides, diagrams, API declarations and recorded executions.

Install tools and build

You need the simulator and example tools, plus Doxygen and Graphviz. On Ubuntu:

sudo apt install doxygen graphviz

From the repository root, create the documentation environment and build the example executables:

uv sync --frozen --group docs
source .venv/bin/activate
cmake --preset gcc-ninja -DBUILD_TESTING=ON
cmake --build --preset gcc-ninja --parallel
python -m sphinx -n -W --keep-going -b html -D qsbit_build=build-gcc docs out/documentation-preview/html

Numerical backend packages are not needed. Select another simulator build with -D qsbit_build=BUILD_DIRECTORY.

Sphinx extracts declarations from the current headers and runs the compiled Bell and feedback programs with mock outcomes. It checks their event times before writing the trace data used by the player. Generated HTML, XML and traces stay under the output directory.

Preview

python -m http.server 8000 --bind 127.0.0.1 --directory out/documentation-preview/html

Open localhost:8000. Keep the server running while you browse; press Ctrl+C to stop it.

Edit pages and diagrams

Edit Markdown under docs/ and add new pages to a toctree in index.md.

Module pages describe their connections, behavior, objects, reset and errors. They link to source and registered tests. Doxygen and Breathe generate the C++ API; documentation tests compare interface excerpts with the headers.

architecture.dot shows the controller’s reserve phase, queues, trigger phase, control output and feedback. implementation.dot links all simulator components, including scheduling helpers and backend APIs. Update the relevant diagram and component index when changing an interface. SVG links open component pages in the containing browser window.

Shared visual resources

web/ contains the self-hosted Source Sans 3 and Source Code Pro fonts, color and typography tokens, base application styles, theme selection and the trace player. Sphinx copies these assets into the output’s _static directory. The local replay server and Studio serve the same files.

The documentation uses PyData Sphinx Theme and docs/_static/docs-theme.css. PyData controls the document’s html[data-theme]; standalone applications use qsbit-theme.js. Studio passes its theme selection to its same-origin replay frame.

Edit trace displays

The timeline uses CSS-pixel coordinates. Zoom changes the displayed time range, not the text size. Detail tabs retain the selected record. Module selection shows its latest recorded values below the architecture diagram.

The player reads a trace bundle produced during the website build. Display recorded values directly. Label calculated clock values as derived and show the observation tick beside a last-recorded value.

Use CpuPipelineUpdated for end-of-edge CPU slot occupancy and InstructionRetired for commitment. Queue entries follow enqueue and trigger records; codeword mappings supply their per-port events.

Source links on the rendered site use the checkout’s Git revision. Links in the Markdown files continue to open local source files.

Run website tests

uv sync --frozen --group docs --group docs-test
source .venv/bin/activate
python -m playwright install chromium
cmake --preset gcc-ninja \
  -DBUILD_TESTING=ON -DQSBIT_TEST_WEBSITE=ON
cmake --build --preset gcc-ninja --parallel
ctest --test-dir build-gcc -L 'documentation|website' --output-on-failure

The suite builds with Sphinx warnings treated as errors. Browser tests check links, module diagrams, architecture controls, recorded executions, keyboard tabs, light and dark themes, timeline scale, data font size and text enlargement. CI uploads the HTML, browser captures and test logs as workflow artifacts. After the native, macOS and documentation jobs pass on main, CI publishes the tested HTML to qsbit-sim documentation. Pull requests build and test the website without publishing it. To republish main, run the Build and verify workflow from the repository Actions tab.