Building and hosting these docs¶
The docs are a Sphinx site written in Markdown
(MyST). The source is the docs/ folder. The API pages are read from the source
code by sphinx-autoapi, so building the docs needs neither KLayout, KQCircuits nor AEDT.
What is where¶
Path |
What |
|---|---|
|
Sphinx settings: theme, MyST options, API reference |
|
Home page and the table of contents (the |
|
The docs toolchain (Sphinx, MyST, Furo, sphinx-autoapi, sphinx-copybutton) |
|
The GitHub Actions workflow that builds and publishes the site |
|
Generated: one page per component (pins, parameters, LOM) |
|
Hand-written notes, included in that cell’s generated page |
|
Generated: the |
|
Images used by the pages: |
|
Thin pages that include |
Build locally¶
Use a separate env for the docs tools, so the qcd env stays as tested:
conda create -n qcc-docs python=3.11
conda activate qcc-docs
pip install -r docs/requirements.txt
sphinx-build -b html docs docs/_build/html
start docs\_build\html\index.html
docs/_build/ is git-ignored. For a live preview while you write, pip install sphinx-autobuild and run
sphinx-autobuild docs docs/_build/html.
Regenerate the generated pages¶
These need the qcd env, because they build the cells with the library:
conda activate qcd
python scripts/make_docs.py REM component pages + qcc reference
python scripts/make_docs.py --render REM also draw pin pictures for new components
Commit the regenerated pages. The publishing workflow only renders them; it does not run the library.
Add a page¶
Write a
.mdfile underdocs/, for exampledocs/plugin/routing.md.Add its path (without
.md) to atoctreeblock indocs/index.md, or in a section page.Put its images in
docs/images/<topic>/and link them relatively:.
MyST adds a few blocks to plain Markdown:
:::{note}
A note box.
:::
```{include} ../../kplugin/README.md
```
Host it¶
The docs are published on GitHub Pages at https://quantcore-technologies.github.io/Quantcore-Circuits/. The workflow
.github/workflows/docs.yml installs docs/requirements.txt, runs the same sphinx-build -b html docs as the local
build (with the API reference) and deploys the result to GitHub Pages. It runs on every push to main and can be started
by hand from the repository’s Actions tab. In the repository’s Settings > Pages, the source must be set to
GitHub Actions.
To check what the workflow will publish, build locally as above. For a quick look on one machine without a browser
file URL: python -m http.server -d docs/_build/html 8000, then open http://localhost:8000. To host a copy
elsewhere, copy docs/_build/html to any web server or file share.