Repository navigation
Add a minimal Sphinx docs build with reno release notes - #43
Open
Jim Garrison (garrison) wants to merge 4 commits into
Open
Jim Garrison (garrison) wants to merge 4 commits into
Jim Garrison (garrison) wants to merge 4 commits into
Conversation
The project had no documentation build at all: no `docs/`, no reno, and no docs CI. Everything user-facing lived in the README, whose hand-written "API Reference" section duplicated the module structure by hand and was free to drift from the code. This adds the smallest thing that is actually real: an API reference generated from the existing docstrings, a working reno setup, and a CI job that fails a pull request when either breaks. Guides and notebooks are deliberately out of scope and can be layered on later without redoing any of this. Two properties of this package shaped the setup. First, autodoc needs the package genuinely installed rather than merely on `sys.path`: the import name `sbd` does not match its directory `python/`, and only setuptools knows the `package-dir` mapping, so the docs environment builds and installs the wheel like the test environments do. Second, importing `sbd` is cheap and GPU-free because backends load lazily, so a CPU-only build on a GPU-less runner is enough to document it. Two details differ from the equivalent setup in qiskit-addon-sqd, where a verbatim copy would have been wrong here: - `linkcode_resolve` needs two separate spellings, since the installed directory (`sbd/`) and the in-repository directory (`python/`) differ. Using one token for both would 404 on every "source" link. - The `sbd` page excludes the `sbd_solver` member. It appears in `sbd.__all__` as a submodule while also having a page of its own, which is a duplicate object description and therefore fatal under `-W`. Enabling `-W` surfaced two pre-existing docstring defects, both fixed here: an unmarked indented block in `assemble_rdms` is now a literal block, which also renders the index formulas as intended, and the over-indented alias list in `init` is reflowed to the indentation napoleon expects. Note that reno only sees notes that git tracks, so a newly added note must be staged before it renders. The release-notes page is also cached across incremental builds; `tox -e docs-clean` forces it to be regenerated. Assisted-by: Claude Opus 5
#44 moved the examples from python/examples to examples/, grouped by basis type, and split the installation documentation out of the README into INSTALL.md. The landing page's getting-started paragraph predated both: it sent readers to the README for the build environment variables, which are now in INSTALL.md, and linked python/examples, which #44 left behind as a signpost holding no scripts. Name all three files for what they now cover. Assisted-by: Claude Opus 5
The `sbd` module docstring and `DeviceConfig`'s both introduced an indented
example with a single colon, which RST reads as a blockquote of body text. The
examples were typeset as prose: the heading ran straight into the first line
("Usage:import sbd"), the blank lines inside collapsed, and the quotes were
rendered as curly ones.
Use the double colon that marks a literal block, as `assemble_rdms` already
does, so the examples get a real code block with highlighting.
Assisted-by: Claude Opus 5
Jim Garrison (garrison)
marked this pull request as ready for review
October 7, 2026 17:55
Jim Garrison (garrison)
added
the
documentation
Sophia Wen (hfwen0502)
added a commit
that referenced
this pull request
Oct 7, 2026
#43's API reference documents every public-named function in sbd.sbd_solver, because the module has no __all__. extract_carryover and rank_carryover_from_amplitudes are internal to _solve_sci_core and would have appeared there, so prefix them with an underscore. Nothing outside the module calls them. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This branch has not been deployed
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
1 participant
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.
This project had no docs build at all. This adds the smallest real one, modeled on
qiskit-addon-sqd: an API reference generated from the existing docstrings, a working reno setup, and a CI job that fails a pull request when either breaks. Guides and notebooks are out of scope and can be layered on later.What's here
docs/withconf.py, a landing page, a release-notes page, and one API page per module (sbd,sbd.sbd_solver,sbd.device_config), using theqiskit-ecosystemtheme.releasenotes/floored atearliest_version: 1.6.1, with no backfilled notes — reno attaches a note to the commit it lands in, so notes written now would show up under "Upcoming release" rather than under the shipped 1.6.1 tag.docsextra andtox -e docs/tox -e docs-cleanenvironments..github/workflows/docs.yml, building on pushes and pull requests, deploying to GitHub Pages only frommain.Details
The docs environment builds and installs the wheel rather than just adding to
sys.path, because autodoc has to import the package: the import namesbddoesn't match its directorypython/, and only setuptools knows that mapping. That's also why the CI job installs MPI and BLAS.linkcode_resolveuses two separate path spellings, since the installed directory (sbd/) differs from the in-repository one (python/); a single token would 404 on every "source" link. Thesbdpage excludes thesbd_solvermember, which is insbd.__all__as a submodule while also having its own page — a duplicate object description, fatal under-W.The build runs with
-W, which surfaced two pre-existing docstring defects inpython/, fixed here: an unmarked indented block inassemble_rdmsbecomes a literal block, and the over-indented alias list ininitis reflowed to the indentation napoleon expects.The deploy job needs GitHub Pages enabled on the repo with source set to "GitHub Actions". Until then it will fail on
main; pull requests are unaffected since deploy is gated onrefs/heads/main.This pull request was generated by Claude Opus 5 under my guidance.