Building these docs¶
Questions about building and hosting this documentation. The full guide is Building and hosting.
Building¶
How do I build the docs?¶
In the separate qcc-docs env, not qcd: pip install -r docs/requirements.txt, then
sphinx-build -b html docs docs/_build/html. The API pages are read from the source by sphinx-autoapi, so the build
needs neither KLayout, KQCircuits nor AEDT. docs/_build/ is git-ignored. See Building and hosting.
The build takes long while I write pages. Can I skip the API?¶
Yes: set QCC_DOCS_FAST=1. It skips the API reference, so a build takes seconds to a minute. A full build writes docs/reference/api/ into the source tree
while it runs.
Where do the component pages come from?¶
They are generated: python scripts/make_docs.py in the qcd env writes one page per component (pin picture, pins table,
parameters and LOM) and the qcc reference; --render also draws pictures for new components. Hand-written notes go in
docs/components/notes/<Cell>.md. Commit the regenerated pages: the hosted docs only render what is in the repository.
Where do I put images?¶
In docs/images/<topic>/, linked relatively from the page.
Can I use tabs or cards in a page?¶
No. Only MyST Markdown with tables, admonitions, figures, toctrees and math is available; sphinx-design and sphinx-togglebutton are not installed.
Hosting¶
How do I host the docs?¶
The docs are published on GitHub Pages at https://quantcore-technologies.github.io/Quantcore-Circuits/. You can also
build them locally and copy docs/_build/html to any web server. See Building and hosting.
Can I host the docs on Read the Docs?¶
The free readthedocs.org serves public sites only. The repository is public and licensed GPL-3.0-or-later (the code builds on KQCircuits), so a public host works.