docs: modernize documentation structure - #167
Open
galjos wants to merge 31 commits into
Open
Conversation
Codecov Report❌ Patch coverage is
Additional details and impacted files@@ Coverage Diff @@
## dev #167 +/- ##
==========================================
- Coverage 96.34% 96.33% -0.01%
==========================================
Files 177 177
Lines 9374 9393 +19
==========================================
+ Hits 9031 9049 +18
- Misses 343 344 +1
🚀 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
galjos
commented
Sep 1, 2026
galjos
left a comment
galjos
left a comment
Member
Author
There was a problem hiding this comment.
Large docs draft — leaving a full pass for later. Scope and validation notes in the PR body look solid; merge after the small fix batch if still current vs dev.
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
Vacuum trajectories are rejected, legacy RDF binning uses half the shortest box edge, analysis objects are single-use, and the developer guide keeps the performance-validation rules from dev.
galjos
force-pushed
the
agent/modernize-docs
branch
from
September 6, 2026 08:58
289a3f4 to
f0ebda3
Compare
Add a Learn the Python API page for file wrappers, in-memory objects and tables, and put a short Python recipe on every method guide and getting started.
Ship a 25-frame isolated water molecule plus Hessian so CLI and Python recipes in the manual can be copy-pasted from a clone.
Give the Lark string grammar a user-facing page with the water fixture as the worked example, including Python Selection.select.
Run the bundled water fixture from trajectory inspect through RDF and MSD, and render the figure in the Sphinx build so API drift fails CI.
CLI and Python snippets now use examples/water. Vibrational analysis shows a runnable input before the Hessian algebra.
The path is not on dev yet, so linkcheck 404s. The clone instructions are enough.
Selection precedence text contradicted the parser (#185) and the list example raised PQTypeError. Vibrations described the inertia tensor of uncentered coordinates; the code centers first. Drop the bit-for-bit claim over a truncated excerpt and three comments that no longer hold.
The rdf()/read_analysis_table snippet lived on five pages; keep it on getting-started and python-api. Drop the three sentences stamped onto every method page, fold the RDF interpretation bullets into the validity section, and state the fixture disclaimer once per page.
Parenthetical em dashes become commas or parentheses, the momentum and vibration caveat lists become definition lists, the method index on the Python page becomes a table, and plot labels use mathtext throughout.
Each analysis page now holds the estimator, input, output, Python recipe and a short checklist. Derivations, legacy-path notes and validity discussion move to a nested <method>-details page. Momentum stays a single page with the recipe moved up.
Tested all console and python blocks in the user-facing pages, as scripts and as notebook cells. Fixes: - getting-started: the --export rerun collided with rdf.dat from the previous step; convert the existing table first, rm before rerunning. - File wrappers (rdf(), msd(), vacf(), vibrations()) resolve input-file paths against the working directory, so calling them from the repo root with examples/water/rdf.in failed. Use contextlib.chdir in python-api, reload the table in getting-started, and show only the direct calculate() route on the vibrations page. - workflow: add copyable Matplotlib code; the plot directive alone left the reader without the plotting step. - analysisOutputFiles: second convert example no longer rewrites rdf.csv.
Filenames written in a PQAnalysis input file (traj_files, out_file,
log_file, restart_file, moldescriptor_file, charge_file(s), spectrum_file,
windowed_out_file, structure_file, hessian_file, normal_modes_file,
modes_file, modes_prefix) now resolve against the directory containing
the input file instead of the working directory. Glob patterns expand in
that directory too. Absolute paths and command-line/API arguments such as
--export / export_files are unchanged.
pqanalysis rdf examples/water/rdf.in and rdf("examples/water/rdf.in")
therefore work from the repository root and write next to the input file.
For an input file in the working directory nothing changes.
The RDF companion-file inference derives its candidates from the raw
trajectory name so the inferred values are resolved exactly once.
Docs drop the contextlib.chdir workaround and describe the rule in the
input-file guide.
Furo centers table captions and Sphinx centers tables narrower than the text column; browsers center th. Tables now sit on the text margin with the caption above, left-aligned, in the same secondary style as figure captions, and all cells left-aligned and top-anchored. The CLI table directive no longer requires a title; the three captions that repeated the heading above them are dropped.
galjos
marked this pull request as ready for review
September 6, 2026 21:27
Every table sits under a heading or an introducing sentence that already names it. The Required/Optional keys tables in the input-reader docstrings keep their captions, which distinguish the two adjacent tables.
No block relies on a caption any more: each table and code block follows a heading or a sentence that names it. The three VACF output tables get their own file-name subheadings; the method pages say which file the input block is saved as; the input-reader docstrings introduce the required and optional key tables in prose instead of captions.
The sentence before each plot now carries what the caption said (analytic schematic vs. fixture data, window parameters, mode cut-off). The figures themselves have labelled axes and legends. Removes the now unused figcaption style.
Naming both topology files enables no_intra_molecular by itself; the RDF
pages said it was only ever explicit. hessian_sign accepts 1 and -1 in input
files too, not only from Python. The vibrations column order is force
constant then reduced mass. fit_window defaults to max(2, window // 5).
Momentum lists three precision paths, not two. data/index.rst still described
filenames resolving against the working directory.
Removes the --export block duplicated on the landing page, two sentences
repeated within the vibrations and RDF details pages, and filler
("simply", "This means that", "fully", "continue to work").
The pq-cli-table :title: option and the table caption CSS had no remaining users after the caption removal. conf.py imported __version__ behind a guard that could not save a build in which the extension and plot scripts import the package unguarded. The reader built the glob root with os.path beside a pathlib base_dir; both now come from base_dir. The VACF plot legend is formatted from the window parameter instead of repeating its value.
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
examples/water), an atom-selection page and a load-RDF-MSD-plot workflowLibrary change (separate commit,
feat:)Filenames inside an analysis input file (
traj_files,out_file,restart_file,hessian_file, ...) and glob patterns now resolve against the directory of the input file instead of the working directory.pqanalysis rdf examples/water/rdf.inandrdf("examples/water/rdf.in")therefore work from the repository root and write next to the input file. Absolute paths and--export/export_filesare unchanged; an input file in the working directory behaves exactly as before. Covered by new reader, RDF-inference and end-to-end tests.This is a behaviour change for anyone who runs
pqanalysis rdf subdir/rdf.inwith data paths written relative to the shell's working directory.Rebased onto current
devuserGuide/developerGuideconflicts by keeping the task-oriented redirect and modern development guidedelta_rnote restoredCleanup after review
Test plan
python -m sphinx -W -b html docs/source docs/build/htmlconsoleandpythonblock in the user-facing pages extracted and executed: 12 CLI commands fromexamples/water, 9 page sessions as scripts, 26 cells as a Jupyter notebook (inline figure renders)python -m pytest tests(1056 passed)