docs: package-wide docstring standardization - #488
Merged
Conversation
Codecov Report✅ All modified and coverable lines are covered by tests.
🚀 New features to boost your workflow:
|
Contributor
|
After the build completes, the updated documentation will be available here |
Write down the conventions the package-wide docstring pass applies: section headings, `- name::Type: description` argument lists, cross-linking with `@ref` / `@extref`, `@cite` references, and how algorithm types document their fields and constructors. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
`SketchedExpand`'s docstring cites the controlled-bond-expansion paper, so add the corresponding bibliography entry. Rename the one capitalised citation key to `hubig2015` for consistency with every other key in the file, and update the `@cite` in `DMRG3S` to match. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Prose and formatting pass over every docstring in `src/`, following `docs/DOCSTRING_STYLE.md`: - unify bullet markers on `-` and argument lists on `- name::Type: description` - promote `##` section headings to `#`, and order them consistently (signature, description, arguments, keywords, returns, examples, see-also, references) - switch algorithm types to `$(TYPEDEF)`/`$(TYPEDFIELDS)` with per-field docstrings, and document their constructors under `# Constructors` - add `Used as the ... argument of [...](@ref)` cross-links so algorithm types point back at the driver they plug into - link upstream API with `[text](@extref Pkg.name)` (KrylovKit, MatrixAlgebraKit, TensorOperations) instead of naming it in plain text - normalise spacing in type parameters and keyword defaults (`PeriodicArray{T,1}` -> `PeriodicArray{T, 1}`, `side=:both` -> `side = :both`) - add `@cite` references where an algorithm has a canonical paper - new or substantially expanded docstrings for the quasiparticle state types, the finite environment types, and several driver functions, with runnable `jldoctest` examples on the main entry points Also drop a link to a non-existent `entanglement_spectrum` anchor in `entanglementplot`, retargeting it at the `entanglement_spectrum` docstring. This commit changes documentation only. Verified by stripping docstrings, comments and blank lines from both `origin/main`'s version and this one of every touched file and diffing the results, which is empty. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
…ansion `trunc` Three follow-ups to the package-wide docstring pass: - Replace the remaining uses of "enrich" with the package's own bond-expansion vocabulary, matching `alg_expand`/`changebond!`/`OptimalExpand`. - Format the code inside docstrings with Runic. Every fenced `julia`/`jldoctest` block was already clean; the drift was in the indented signature blocks. Enable `--docstrings` in the pre-commit hook so this stays enforced locally, and hand-fix the blocks Runic silently skips (docstrings with `$(TYPEDEF)` interpolation, and blocks that are not parseable Julia). Note that CI cannot enforce this: the shared QuantumKitHubActions FormatCheck workflow runs plain `git runic --diff` and takes only a `julia-version` input, so the hook is deliberately stricter than the CI check. - Spell out that the `trunc` of `OptimalExpand`, `RandExpand` and `SketchedExpand` bounds how many directions are *added* to each bond, not the total bond dimension that is kept -- the opposite of what the same keyword means on `SvdCut` and on the drivers. It is applied to the orthogonal complement (or, for the randomized expanders, to random weights), so `truncrank`/`truncspace` are the strategies with a robust meaning there. Also fixes the `MPO` docstring naming its type parameter `O` where the struct declares `TO`, a "this is happens" typo, `RandExpand` prose that described only the infinite code path, and the double-hash section headers plus section order in the `Zipup` docstring. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
lkdvos
marked this pull request as ready for review
August 2, 2026 12:38
- `exact_diagonalization`: drop the documented `len` keyword. The function takes no such keyword -- it derives `L = length(H)` internally -- so passing it would be a `MethodError`. The documented signature now matches the definition exactly. - `ChepigaAnsatz2`: move the hand-written `# Fields` bullets onto the struct as per-field doc strings rendered by `$(TYPEDFIELDS)`, matching `ChepigaAnsatz` and template A1. The defaults stay in the field strings, since the fields are positional and the constructor supplies them. - Drop the "Physics claims" section from the style guide. The `<!-- REVIEW -->` convention it described does not work in a docstring: DocumenterVitepress escapes HTML comments, so they render as visible body text on the page. Record that as an "Attachment" rule instead, next to the docstring-detaching comment. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
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.
Docstring standardization slice of #449, re-applied on top of current
main: a newdocs/DOCSTRING_STYLE.mdand its conventions applied to 53 files undersrc/— unified bullets and argument lists, a fixed section order,$(TYPEDEF)/$(TYPEDFIELDS)for algorithm structs,@extreflinks to upstream APIs, driver ↔ algorithm cross-links, and runnablejldoctestexamples on the main entry points.Documentation-only. Stripping docstrings and comments from every touched
src/file and diffing againstmaingives an empty result — no code changed. The three genuine code changes hiding in #449'ssrc/diff went to #489 instead.Two things beyond the style pass:
src/utility/plotting.jllinked(@ref entanglement_spectrum), an anchor that exists nowhere; sincelib/lib.mdautodocs the whole module, this fails the build. Retargeted at the realentanglement_spectrumdocstring.trschemebytrunc#482 (trscheme→trunc) and Refactor MPSTensor construction to fix type piracy #475 (removedMPSTensorconstructors), so it was applied as a patch keepingmain's code; the affected docstrings and onejldoctestwere rewritten accordingly.Also adds two
mpskit.biblines these docstrings need: thegleis2023entry, and theHubig2015→hubig2015rename with its@cite. Expect a one-line conflict with #487 on that key; take lowercase.Doctests pass and the Documenter half of the build is clean; the
vitepress buildstep can't run on my machine (host glibc too old for rollup), so CI should confirm the HTML render.🤖 Generated with Claude Code