docs: modernize documentation structure - #167
Draft
galjos wants to merge 14 commits into
Draft
Conversation
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## dev #167 +/- ##
=======================================
Coverage 93.86% 93.86%
=======================================
Files 177 177
Lines 9215 9215
=======================================
Hits 8650 8650
Misses 565 565
🚀 New features to boost your workflow:
|
galjos
marked this pull request as ready for review
August 7, 2026 11:00
galjos
marked this pull request as draft
August 7, 2026 11:01
# Conflicts: # docs/source/developerGuide/developerGuide.rst # docs/source/userGuide/userGuide.rst
Address the review of the documentation draft: - add a configure-pages step with enablement so the first Pages deploy switches the repository source to GitHub Actions instead of failing against the legacy gh-pages setting - set sitemap_url_scheme to the plain link so the sitemap matches the flat deployed site instead of 404ing on language/version prefixes - correct the build_nep_traj description (Neuroevolution Potential training data, not nudged elastic band) - stop tracking the generated docs/source/code pages and ignore them together with docs/build, so local docs builds no longer dirty the working tree; drop the stale docs/autodoc.sh that conflicted with the better-apidoc build - clarify that only conversion/support tools accept --mode o; the input-file analyses have no overwrite flag - remove the orphaned reference/index.rst page and the unused breathe docs dependency; include momentum in the Cython-kernel list; ignore the generated momentum kernel source
Add a small local Sphinx extension with a pq-cli-table directive that renders the command tables of the command-line reference and validates them at build time: every listed name must exist in the pqanalysis command registry, and after reading all pages every registered command must be documented exactly once (prose-documented commands are marked with pq-cli-covered). A renamed, removed or newly added command now fails the strict documentation build instead of silently drifting out of the reference tables. The purpose texts stay editorial.
The command-table extension scraped the attributes of the dispatcher module. During the documentation build the api-doc generator imports the package at the same time, so the dispatcher could be observed half-initialized and the extension then saw no commands at all and rejected every documented one. The strict build failed on CI while passing locally, because the outcome depended on import order. Read the dispatch table from the module source with ast instead and import only the individual command modules, which have no import cycle with the dispatcher. Raise immediately if the table cannot be read, so an unreadable registry can no longer look like an empty one.
The dispatcher now keeps a lazy table that maps every command name to its module, class and description, so the command tables of the reference can be validated by reading that table alone. Parse it from the module source and drop the import of the individual command modules: the extension no longer depends on import order or on the package being importable at all, and a table it cannot read is reported instead of silently looking empty.
The analysis pages described what the software computes but not where the methods come from or when their results can be trusted. - add a references page with the primary sources for every implemented estimator, and cite them from the analysis pages where the quantity is defined; state that the project has no citable DOI of its own yet - give the vibrational analysis its mathematics: the mass-weighted Hessian and its eigenproblem, the wavenumber conversion with its unit chain, the automatic sign heuristic, force constants, reduced masses and infrared intensities, each matching the implementation - describe the linear momentum as a drift diagnostic and state the precision floor below which a reported norm is parsing noise - add validity and interpretation sections to the radial distribution, mean square displacement and velocity autocorrelation pages: the minimum-image limit on r_max, the diffusive regime and fit window, the frequency resolution and Nyquist limit, and that no finite-size correction of the diffusion coefficient is applied
Contributor
|
PYLINT REPORT Your code has been rated at 9.78/10 Full reportRaw metrics
Duplication
Messages by category
% errors / warnings by module
Messages
|
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.
Scope
Re-evaluation after #168 and #169
devbranch into this branchValidation
867 passed, 4 skippedin release type-checking modeThis PR remains a draft and is not merged. The repository Pages source is still
gh-pages; changing that setting is outside this draft.