docs: regenerate INPUT parameter docs in RTD build#7621
Conversation
There was a problem hiding this comment.
Pull request overview
This PR updates the Read the Docs (RTD) build to compile a reduced ABACUS binary and regenerate INPUT parameter documentation artifacts during the Sphinx build, keeping published docs aligned with the current executable’s parameter metadata.
Changes:
- Extend
.readthedocs.yamlto install build deps, buildabacus_pw_ser, and regeneratedocs/parameters.yamlbefore Sphinx runs. - Regenerate
docs/parameters.yamlanddocs/advanced/input_files/input-main.mdfrom the binary/YAML. - Adjust
docs/generate_input_main.pydefault-value rendering for multiline defaults.
Reviewed changes
Copilot reviewed 4 out of 4 changed files in this pull request and generated 7 comments.
| File | Description |
|---|---|
.readthedocs.yaml |
Adds RTD pre-build steps to compile a reduced binary and regenerate docs/parameters.yaml before Sphinx. |
docs/generate_input_main.py |
Updates markdown generation for multiline default values. |
docs/parameters.yaml |
Regenerated parameter metadata YAML committed to the repo. |
docs/advanced/input_files/input-main.md |
Regenerated INPUT keyword reference markdown from parameters.yaml. |
| @@ -1379,7 +1393,6 @@ parameters: | |||
| * berendsen: Berendsen thermostat, see md_nraise in detail. | |||
| * rescaling: velocity Rescaling method 1, see md_tolerance in detail. | |||
| * rescale_v: velocity Rescaling method 2, see md_nraise in detail. | |||
| description: | | ||
| It's the density threshold for electronic iteration. It represents the charge density error between two sequential densities from electronic iterations. This criterion is always enabled. If `scf_ene_thr` is set, the total-energy criterion (`scf_ene_thr`) is evaluated conditionally after the charge-density criterion (`scf_thr`) is satisfied, and not on the first iteration. For local-orbital calculations, 1e-6 is usually accurate enough. | ||
| It's the density threshold for electronic iteration. It represents the charge density error between two sequential densities from electronic iterations. Usually for local orbitals, usually 1e-6 may be accurate enough. | ||
| default_value: "1.0e-9 (plane-wave basis), or 1.0e-7 (localized atomic orbital basis)." |
| description: | | ||
| It's the energy threshold for electronic iteration. The compared quantity is the total-energy difference evaluated from the charge densities before and after the `Hpsi` operation in one SCF step. It is not the same as the screen-output `EDIFF`, which is the energy difference before `Hpsi` and after charge mixing (i.e., across both `Hpsi` and charge-mixing operations). | ||
| It's the energy threshold for electronic iteration. It represents the total energy error between two sequential densities from electronic iterations. | ||
| default_value: "-1.0. If the user does not set this parameter, it will not take effect." |
| * bfgs: BFGS quasi-Newton method | ||
| * linear_response: linear response (Scheme B) | ||
| * augmented_lagrangian: augmented Lagrangian (Scheme C) | ||
| * hybrid_delayed: hybrid delayed update (Scheme D) | ||
| * linear_scan: linear sweep of lambda for testing magnetic moment response |
| if param.get('default_value', '') != '': | ||
| default_text = escape_md_text(str(param['default_value'])) | ||
| lines.append(f"- **Default**: {default_text}") | ||
| default_text = escape_md_text(str(param['default_value'])).strip('\n') |
| - name: sc_scan_lambda_start | ||
| category: Spin-Constrained DFT | ||
| type: Float | ||
| description: | | ||
| Starting lambda value for linear_scan strategy. Only used when sc_lambda_strategy=linear_scan. |
| - 3: Apart from 1, also output the total local potential of the initial charge density. The files are named as: | ||
| - nspin = 1: pots1_ini.cube; | ||
| - nspin = 2: pots1_ini.cube and pots2_ini.cube; | ||
| - nspin = 4: pots1_ini.cube, pots2_ini.cube, pots3_ini.cube, and pots4_ini.cube | ||
| - out_freq_ion = 0: | ||
| - nspin = 1: `pot_ini.cube`; | ||
| - nspin = 2: `pots1_ini.cube` and `pots2_ini.cube`; | ||
| - nspin = 4: `pots1_ini.cube`, `pots2_ini.cube`, `pots3_ini.cube`, and `pots4_ini.cube`; |
💡 Codex Reviewabacus-develop/.readthedocs.yaml Line 45 in 2ee94ed  Preserve EXX inputs when regenerating parameter YAML
This RTD step now regenerates Keep csvr listed as a thermostat option
For NVT users who need CSVR, this regenerated list no longer includes Document the CNPY requirement for npz outputs
For users following the docs from a build without CNPY, this regenerated description drops the previous CNPY prerequisite even though ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
If Codex has suggestions, it will comment; otherwise it will react with 👍. Codex can also answer questions or update the PR. Try commenting "@codex address that feedback". |
|
Addressed the Codex review items:
Ignored Copilot wording/format comments intentionally, since those are generated docs and broader parameter wording cleanup is outside this PR scope. Verification:
Result: build and docs generation passed; Sphinx completed with the existing docs warnings. |
|
If this workflow is successful, we can even drop |
|
Addressed this in commit 003c1a5 by adding docs/README.md with local manual build instructions, INPUT-reference regeneration steps, and an optional RTD container smoke test. Checked the generated-file question as well: RTD no longer depends on a committed docs/parameters.yaml because .readthedocs.yaml regenerates it before Sphinx runs, and a local Sphinx build succeeds without docs/parameters.yaml when the checked-in input-main.md is present. |
|
I think parameters.yaml can be dropped from the repository. However, we still need instructions/checks to make sure that the inputs-main.md is consistent with the actual source code. As in #7592. |
|
Updated the PR to remove the checked-in docs/parameters.yaml middleware. The docs build now refreshes docs/advanced/input_files/input-main.md directly from an ABACUS executable during Sphinx startup. If no executable is available, it emits a warning and keeps the checked-in generated page.\n\nOther updates: .readthedocs.yaml now only builds the reduced binary, CI checks input-main.md against transient generated YAML, and the contributor/governance docs plus docs/README.md describe the new flow. Added focused unittest coverage for binary refresh and missing-binary warning behavior.\n\nVerification run:\n- cmake configure for reduced docs binary: passed\n- cmake --build build-rtd-docs --target abacus_pw_ser --parallel 2: passed\n- OMP_NUM_THREADS=1 ./build-rtd-docs/source/abacus_pw_ser --generate-parameters-yaml | python docs/generate_input_main.py - --output docs/advanced/input_files/input-main.md: passed, 525 parameters\n- python -m unittest docs.tests.test_conf_input_docs: passed, 2 tests\n- ABACUS_BINARY=./build-rtd-docs/source/abacus_pw_ser sphinx-build -b html docs /tmp/abacus-rtd-sphinx-html-no-yaml-middleware-final: passed, 37 existing warnings\n- git diff --check: passed |
|
Sorry but, is I personally suggest to report error status if there is failure while generating |
Linked Issue
Related to #7592.
Unit Tests and/or Case Tests for my changes
No unit/case tests added. This changes the documentation build path and regenerated docs artifacts only.
Exact Verification Performed
abacus_pw_serdocs/parameters.yamlwith--generate-parameters-yamldocs/advanced/input_files/input-main.mdreadthedocs/build:ubuntu-22.04-2024.01.29docs/parameters.yamldocs/advanced/input_files/input-main.mdResult: builds passed; Sphinx completed with existing docs warnings.
What's changed?
abacus_pw_serbefore Sphinx runs.docs/parameters.yamlfrom the freshly built binary.docs/parameters.yamlandinput-main.md.generate_input_main.pyto avoid trailing whitespace.INPUT Parameter Changes
docs/parameters.yamlupdated: yesdocs/advanced/input_files/input-main.mdupdated: yesCore Module Impact
None. No ABACUS runtime behavior changes.
Governance Exception
None.