Add a minimal Sphinx docs build with reno release notes - #43
Draft
Jim Garrison (garrison) wants to merge 1 commit into
Draft
Jim Garrison (garrison) wants to merge 1 commit into
Jim Garrison (garrison) wants to merge 1 commit 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
Comment on lines
+18
to
+21
| Installation, the environment variables that control which backends are compiled, and | ||
| runnable examples are documented in the `README | ||
| <https://github.com/Qiskit/sbd-eigensolver-python/blob/main/README.md>`__ in the root | ||
| of this project's repository. Example scripts and a notebook live in `python/examples |
Member
Author
There was a problem hiding this comment.
This sentence may need a slight tweak once #44 merges.
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.