Repository navigation
docs: migrate to the tprocv2-era documentation tree - #430
Merged
Merged
Conversation
Replaces the pre-tprocv2 flat docs/ tree (tProc v1 + SG-v4 era: a single firmware.rst channel-assignment model, asmv1_cheatsheet.rst, no per-IP-core reference pages) with the restructured docs/source/ tree developed and audited in openquantumhardware/qick_internal. What's new, at a glance: - Full tProc v2 reference manual (tprocv2_trm.rst) plus a dedicated legacy tProc v1 page (tprocv1.rst) for users on older boards. - One reference page per readout/generator IP core (avg_buffer, mr_buffer_et, readout_v2, readout_dynamic, readout_pfb, kidsim, sg_v6, sg_v4, sg_int4_v2, sg_mux8, sg_mixmux8) plus family-overview pages (readout.rst, generators.rst) explaining which core to use for which experiment. - The 00-14 tutorial notebook series (nbsphinx-rendered). - A restructured "Software API" reference page with a real intro instead of a bare module list. - Corrected topics/ pages (asmv2_cheatsheet, timing, units, freq_matching, xcom, XCOM-commands, pyro4, playing_pulses, ...) -- several had fictional API calls or bit-encoding errors going back to the tProc v1 architecture that never got updated for v2. Every page was cross-checked against qick_lib source (and, for firmware-level claims, RTL) in the source repo before this migration; see qick_internal's fix-tprocv2-trm-docs branch history for the detailed per-page verification notes. Build infra changes: - docs/ -> docs/source/ (Sphinx source root now has its own subdirectory; docs/Makefile's SOURCEDIR already expected this). - .readthedocs.yaml: sphinx.configuration -> docs/source/conf.py, python.install requirements path unchanged (docs/requirements.txt, which already lists myst-parser and nbsphinx), added the `pandoc` apt package nbsphinx needs to render notebooks. - .gitignore: docs/_build|_autosummary -> docs/source/_build| _autosummary. Kept as-is (not part of the tprocv2 restructuring, independently maintained): papers.rst and its chart images -- the source repo's copy had fallen behind this repo's (missing 3 recently-added papers, the Qblox QICK box link, and the "At a glance" stats section) -- verified contact.rst and quick_start.rst have NOT drifted the same way before carrying those over unchanged. Verified with a full local sphinx-build against this repo's own qick_lib: 0 errors, only pre-existing warnings (a handful of docstring formatting issues in qick.py/rfboard.py/ tprocv2_assembler.py, unrelated to this migration).
Content originally proposed in PR #412 by Jay Chien against the old docs/*.rst tree (now superseded by docs/source/, so that PR no longer applies cleanly). Ports it into the current docs/source/topics/ tree, crediting the original author, and verifies every API name used (add_loop, QickSweep1D, get_pulse_param, get_time_param, delay/ delay_auto/wait_auto, AveragerProgramV2.acquire) against qick.asm_v2 and qick.qick_asm. Also fixes the example-code page's Markdown-style headings/links, which were invalid in an .rst file. Verified with a full local sphinx-build: same pre-existing 26-warning baseline, no new warnings from either page.
lharnaldi
force-pushed
the
docs-migration-tprocv2
branch
from
September 5, 2026 20:12
164e334 to
3599e25
Compare
Plain 'make html' fell back to whatever sphinx-build is on PATH (system Sphinx, missing nbsphinx/myst-parser) since nothing pointed it at a venv with docs/requirements.txt installed. Default SPHINXBUILD to ../.venv/bin/sphinx-build when it exists, still overridable via 'make SPHINXBUILD=... html'.
Syncs qick_internal's fix-tprocv2-trm-docs work since the last update: - index.rst reordered for a new-user learning path: tutorials split into their existing Basic/Intermediate/Advanced tiers as separate sidebar captions, firmware overview promoted ahead of the deep tProc v2 TRM, and legacy tProc v1 pushed to its own clearly-marked tier at the end. - 14 hand-drawn circuitikz block diagrams (general firmware system diagram plus one per generator/readout/support core and tProc v2 itself), each verified against the real RTL, not auto-extracted or copied from memory. Sources and the `make tikz-diagrams` build live in qick_internal's firmware/fusesoc/ (private RTL infra); this repo gets the rendered SVGs. Verified with a full local sphinx-build: same pre-existing 26-warning baseline, diagrams and sidebar order confirmed in the built HTML.
kidsim, mr_buffer_et, dyn_readout, and readout_pfb v2/v3 all had connections that landed outside their target box or overlapped a label. Synced from qick_internal.
New tutorial 15 covers QICKBox RF/Balun daughtercards: attenuators, ADMV8818 tunable filters, and saturation checks, adapted from openquantumhardware/QCE2025's qickbox_rf.ipynb (trimmed to the QICKBox-specific content; generic readout/sweep/pulse-sequence material is already covered by tutorials 01/02/05/06/07). Also fixes the generator-types comparison table in tutorial 07: the Full-Speed/Interpolated rows described pulse shaping instead of the actual tradeoff, which is PL logic usage.
Five QickSoc.tt_* docstrings wrote `time_taggers' (backtick open, apostrophe close) instead of matching backticks, which docutils couldn't parse as an inline reference. Synced from qick_internal.
The "Release (March 2024)" banner had an overline but no matching underline, so docutils tried to parse it as a section title and failed. Added the missing underline (matching the FERMI RESEARCH LAB banner above it). Synced from qick_internal.
Contributor
|
Still need to read through and check everything - there is definitely some amount of LLM-generated text and code snippets that is wrong, and some terrible LLM prose that needs to get trimmed. But good enough! |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Replaces the pre-tprocv2 flat
docs/tree (tProc v1 + SG-v4 era) with therestructured
docs/source/tree developed and audited inopenquantumhardware/qick_internal, branchfix-tprocv2-trm-docs.tprocv2_trm.rst) plus a dedicated legacytProc v1 page (
tprocv1.rst) for users on older boards.avg_buffer,mr_buffer_et,readout_v2,readout_dynamic,readout_pfb,kidsim,sg_v6,sg_v4,sg_int4_v2,sg_mux8,sg_mixmux8) plusfamily-overview pages (
readout.rst,generators.rst) explaining whichcore to use for which experiment.
a bare module list.
topics/pages (asmv2_cheatsheet,timing,units,freq_matching,xcom,XCOM-commands,pyro4,playing_pulses, ...) --several had fictional API calls or bit-encoding errors going back to the
tProc v1 architecture that never got updated for v2.
Every page was cross-checked against
qick_libsource (and, forfirmware-level claims, RTL) before this migration.
Build infra changes
docs/->docs/source/(Sphinx source root now has its ownsubdirectory;
docs/Makefile'sSOURCEDIRalready expected this)..readthedocs.yaml:sphinx.configuration->docs/source/conf.py,added the
pandocapt packagenbsphinxneeds to render notebooks..gitignore:docs/_build|_autosummary->docs/source/_build|_autosummary.Kept as-is
papers.rstand its chart images were not overwritten -- this repo'scopy had 3 more recently-added papers, a Qblox QICK box link, and an
"At a glance" stats section that the source repo's copy lacked.
contact.rst/quick_start.rstwere checked for the same kind of drift andfound identical, so those did come across unchanged.
Test plan
sphinx-buildagainst this repo's ownqick_lib: 0 errors,only pre-existing warnings (docstring formatting in
qick.py/rfboard.py/tprocv2_assembler.py, unrelated to this PR).notebook) for formatting.
🤖 Generated with Claude Code