Docs: Generate input reference in CI

.github/instructions/abacus-governance.instructions.md

@@ -22,9 +22,9 @@ Apply these instructions when reviewing or changing ABACUS code:
   usually warnings unless the PR records a narrow reason.
 - Require LF line endings for text files. `.bat` and `.cmd` files are the CRLF
   exceptions.
-- For INPUT parameter behavior changes, require synchronized updates to
-  `docs/parameters.yaml` and `docs/advanced/input_files/input-main.md`, or a
-  clear no-update explanation in the PR.
+- For INPUT parameter behavior changes, require corresponding C++ `Input_Item`
+  metadata updates, or a clear no-update explanation in the PR. Do not require
+  generated YAML or Markdown documentation files to be committed.
 - Check that new source files are linked through the relevant `CMakeLists.txt`
   unless the PR explains generated or indirect inclusion.
 - Keep default C++ changes compatible with the repository C++11 baseline.

.github/workflows/test.yml

@@ -121,34 +121,6 @@ jobs:
           ccache --show-stats
           ccache --show-stats >> "${GITHUB_STEP_SUMMARY}"
 
-      - name: Check documentation consistency
-        run: |
-          ABACUS_BIN=$(find build -name "abacus_*" -type f -executable | head -1)
-          echo "Using binary: ${ABACUS_BIN}"
-
-          # Check 1: parameters.yaml matches C++ Input_Item definitions
-          ${ABACUS_BIN} --generate-parameters-yaml > /tmp/parameters_generated.yaml
-          if ! diff -q docs/parameters.yaml /tmp/parameters_generated.yaml; then
-            echo "error: docs/parameters.yaml is out of sync with C++ source"
-            echo "Fix: ${ABACUS_BIN} --generate-parameters-yaml > docs/parameters.yaml"
-            diff docs/parameters.yaml /tmp/parameters_generated.yaml || true
-            exit 1
-          fi
-          echo "  parameters.yaml: OK"
-
-          # Check 2: input-main.md matches regenerated markdown
-          pip install -q pyyaml
-          python docs/generate_input_main.py \
-            /tmp/parameters_generated.yaml \
-            --output /tmp/input-main-generated.md
-          if ! diff -q docs/advanced/input_files/input-main.md /tmp/input-main-generated.md; then
-            echo "error: input-main.md is out of sync"
-            echo "Fix: python docs/generate_input_main.py docs/parameters.yaml"
-            diff docs/advanced/input_files/input-main.md /tmp/input-main-generated.md || true
-            exit 1
-          fi
-          echo "  input-main.md: OK"
-
       - name: Integrated Tests Preparation
         env:
           GTEST_COLOR: 'yes'

.readthedocs.yaml

@@ -6,9 +6,23 @@ version: 2
 
 # Set the OS, Python version and other tools you might need
 build:
-  os: ubuntu-22.04
+  os: ubuntu-24.04
   tools:
-    python: "3.11"
+    python: "3.12"
+  apt_packages:
+    - build-essential
+    - cmake
+    - gfortran
+    - libfftw3-dev
+    - libopenblas-dev
+    - ninja-build
+    - pkg-config
+  jobs:
+    pre_build:
+      - cmake -Bbuild -GNinja -DCMAKE_INSTALL_PREFIX=install -DENABLE_MPI=OFF -DENABLE_LCAO=OFF
+      - cmake --build build --target install -j $(nproc)
+      - install/bin/abacus --generate-parameters-yaml > docs/parameters.yaml
+      - python3 docs/generate_input_main.py docs/parameters.yaml
 
 # Build documentation in the "docs/" directory with Sphinx
 sphinx:

AGENTS.md

@@ -53,9 +53,6 @@ rules. Read the complete governance document before making or reviewing changes:
 - Use LF line endings for text files. Only `.bat` and `.cmd` files may use CRLF.
 - Keep source file additions deterministic: update the relevant `CMakeLists.txt`
   or explain why the file is generated or included indirectly.
-- INPUT parameter behavior changes must update `docs/parameters.yaml` and
-  `docs/advanced/input_files/input-main.md`, or the PR must state why no update
-  is required.
 - Report the exact verification performed. Do not claim completion without
   fresh test or check output.
 - For multi-step refactors (e.g., splitting a large `.cpp` into several
@@ -72,8 +69,8 @@ rules. Read the complete governance document before making or reviewing changes:
 - Core C++ implementation lives under `source/`; source additions must be wired
   through the relevant `CMakeLists.txt`.
 - INPUT parsing and help metadata live under `source/source_io/`; user-facing
-  INPUT docs live in `docs/parameters.yaml` and
-  `docs/advanced/input_files/input-main.md`.
+  INPUT reference is generated from that metadata during the documentation
+  build.
 - Unit tests are colocated under module `test/` directories such as
   `source/source_md/test/`; integration and workflow tests are selected through
   CTest labels and patterns.

docs/.gitignore

@@ -0,0 +1,2 @@
+advanced/input_files/input-main.md
+parameters.yaml

docs/CONTRIBUTING.md

@@ -101,7 +101,7 @@ These rules apply to human contributors, AI agents, GitHub CI, and CodeRabbit.
 
 Pull requests must complete the governance checklist in the PR template,
 including issue linkage, test evidence, behavior-change notes, INPUT parameter
-documentation linkage, core-module impact, and any requested exceptions. Local
+metadata changes, core-module impact, and any requested exceptions. Local
 pre-commit checks cover deterministic rules such as LF line endings and staged
 diff checks; CI repeats the governance check against the PR diff and PR body.
 
@@ -174,40 +174,18 @@ An practical example is class [LCAO_Deepks](https://github.com/deepmodeling/abac
 
 ABACUS includes a built-in help system that allows users to query INPUT parameters directly from the command line (e.g., `abacus -h ecutwfc`). Parameter metadata is defined inline in the C++ source files under `source/source_io/module_parameter/` using `Input_Item` registrations.
 
-The C++ `Input_Item` registrations are the source of truth for parameter metadata. The checked-in `docs/parameters.yaml` and `docs/advanced/input_files/input-main.md` files are generated artifacts: do not edit either file manually. `parameters.yaml` is generated from the binary and is used by Sphinx to produce `input-main.md`.
+The C++ `Input_Item` registrations are the source of truth for parameter metadata. `docs/parameters.yaml` and `docs/advanced/input_files/input-main.md` are generated during the documentation build and are not tracked in the repository. Do not edit or commit either generated file.
 
 Availability expressions follow the grammar and invariants in
 [`developers_guide/input_availability.md`](developers_guide/input_availability.md).
 
-### When to Update `docs/parameters.yaml`
+When adding, removing, or changing an INPUT parameter, update its `Input_Item`
+metadata together with the implementation. This includes the description, type,
+default value, unit, category, and availability. The generated YAML and Markdown
+will be refreshed automatically when the documentation is built.
 
-You **must** regenerate `docs/parameters.yaml` whenever you:
-
-- Add a new INPUT parameter
-- Remove an existing INPUT parameter
-- Change a parameter's description, type, default value, unit, category, or availability
-
-### How to Regenerate
-
-After building and installing ABACUS, run:
-
-```bash
-abacus --generate-parameters-yaml > docs/parameters.yaml
-```
-
-Then verify the YAML is valid:
-
-```bash
-python3 -c "import yaml; d=yaml.safe_load(open('docs/parameters.yaml')); print(len(d['parameters']), 'parameters')"
-```
-
-Then regenerate the markdown documentation locally:
-
-```bash
-python3 docs/generate_input_main.py docs/parameters.yaml --output docs/advanced/input_files/input-main.md
-```
-
-**Important:** Include the updated `docs/parameters.yaml` and `input-main.md` in your commit when submitting a PR that modifies INPUT parameters. CI regenerates both files from the built binary and rejects any mismatch. Do not fix a documentation mismatch by editing either generated file; update the C++ `Input_Item` registration and regenerate them instead.
+To preview the generated INPUT reference locally, follow the documentation build
+instructions in [`README.md`](README.md).
 
 ### Parameter Documentation Format
 

docs/README.md

@@ -0,0 +1,224 @@
+# ABACUS Documentation
+
+These are the sources of the [ABACUS documentation](https://abacus.deepmodeling.com/). They are
+built by Read the Docs according to [this configuration file](../.readthedocs.yaml).
+
+To build a local version of the documentation, perform the following steps from the `docs/`
+directory:
+
+1. Create and activate a [virtual Python environment](https://docs.python.org/3/tutorial/venv.html):
+
+   ```bash
+   python3 -m venv ../docs_venv
+   source ../docs_venv/bin/activate
+   ```
+
+1. Install the required Python packages:
+
+   ```bash
+   pip3 install -r ./requirements.txt
+   ```
+
+1. (optional but recommended) Build an ABACUS binary and use it to generate the `parameters.yaml`
+   file:
+
+   ```bash
+   ../bin/abacus --generate-parameters-yaml > ./parameters.yaml
+   ```
+
+1. (optional but recommended) Generate Markdown pages from the `parameters.yaml` file:
+
+   ```bash
+   python3 ./generate_input_main.py ./parameters.yaml
+   ```
+
+1. Run Sphinx:
+
+   ```bash
+   make html
+   ```
+
+1. Browse the HTML output in the `build/html` directory.
+
+______________________________________________________________________
+
+# Syntax Cheat Sheet
+
+The ABACUS documentation uses Sphinx with the [MyST parser](https://myst-parser.readthedocs.io) for
+Markdown support. The following gives a quick overview of the syntax:
+
+## Headings
+
+```
+# A first-level heading
+
+## A second-level heading
+
+### A third-level heading
+```
+
+## Basic Text Formatting
+
+```
+**bold text**
+
+_italic text_ (alternatively, *italic text*)
+
+~~strikethrough text~~
+
+`inline code`
+```
+
+For all typography options, see the
+[MyST documentation](https://myst-parser.readthedocs.io/en/latest/syntax/typography.html).
+
+## Links
+
+- Another page: `[](advanced/install.md)`
+  - Use a relative path. The `.md` file extension can be specified or omitted when linking to the
+    page itself.
+- Subsection in the current page: `[](#cross-references)`
+- Subsection in another page: `[](advanced/install.md#build-with-cuda-support)`
+  - Use a relative path and include the `.md` suffix before the `#` sign. Headings up to level four
+    have anchors generated automatically; see [](#cross-references) below for a more stable
+    alternative.
+- External URL: `<https://abacus.deepmodeling.com/>`
+- External URL with label: `[ABACUS documentation](https://abacus.deepmodeling.com/)`
+
+## Cross References
+
+For references that should remain stable when headings or files are renamed, prefer an explicit MyST
+target over an automatically generated heading anchor. Define a target immediately before the
+heading:
+
+```text
+(input-structure)=
+### Structure of the INPUT file
+```
+
+Reference it from the same or another page with the Sphinx `ref` role:
+
+```text
+{ref}`input-structure`
+```
+
+A custom link label can be specified as well:
+
+```text
+{ref}`INPUT structure <input-structure>`
+```
+
+Explicit target names are global within the documentation and should therefore be unique. Use
+ordinary relative Markdown links for simple page links and explicit targets for cross-references
+that are expected to be long-lived.
+
+For more details, see the
+[MyST cross-reference documentation](https://myst-parser.readthedocs.io/en/latest/syntax/cross-referencing.html).
+
+## Lists
+
+For a numbered list:
+
+```
+1. First enumerated item
+1. Second enumerated item
+1. And the third item
+```
+
+> [!NOTE]
+>
+> Every item uses `1.` intentionally in the markdown source file, and the formatting tool in the
+> precommit check will apply this style if detected. The list will still be rendered with the
+> intended numbers as indices on github and the final HTML documentation page, but there is no
+> longer the need to track and edit the numbers manually. For more information, see `mdformat` docs
+> on [ordered lists](https://mdformat.readthedocs.io/en/stable/users/style.html#ordered-lists).
+
+For an unordered list:
+
+```
+- A bullet point
+- Another bullet point
+  - Indented bullet point
+- Yet another bullet point
+* An asterisk is also okay
+```
+
+When nesting levels of lists, watch out for indentations and newlines.
+
+```
+1. 3D periodicity
+  - XYZ
+1. 2D periodicity
+  - XY
+  - YZ
+  - XZ
+1. 1D periodicity
+  - X
+  - Y
+  - Z
+1. non-periodic
+```
+
+## Tables
+
+```
+| foo | bar |
+| --- | --- |
+| baz | bim |
+```
+
+For more table formatting options, see the
+[MyST documentation](https://myst-parser.readthedocs.io/en/latest/syntax/tables.html).
+
+## Math
+
+```
+Inline math: $A_{ia,jb}$.
+
+Math block:
+$$ \begin{align}
+    A_{ia,jb} &= (\varepsilon_a^{GW}-\varepsilon_i^{GW})\delta_{ij}\delta_{ab}
+    B_{ia,jb} &= 2 v_{ia,bj} - W_{ib,aj} \quad .
+\end{align} $$
+```
+
+See also the
+[MyST](https://myst-parser.readthedocs.io/en/latest/syntax/optional.html#math-shortcuts) and
+[MathJax](https://docs.mathjax.org/en/latest/input/tex/index.html) documentation.
+
+## Notes and Warnings
+
+````
+```{note}
+A note box.
+```
+
+```{warning}
+A warning box.
+```
+````
+
+For all available admonitions see the
+[MyST documentation](https://myst-parser.readthedocs.io/en/latest/syntax/admonitions.html).
+
+## Code Blocks
+
+````
+```python
+for i in range(10):
+  print("Hello World")
+```
+````
+
+````
+```text
+calculation             cell-relax
+symmetry                1
+basis_type              lcao
+ecutwfc                 100
+```
+````
+
+The language identifiers like `python` determine syntax highlighting; `text` is the choice for a
+plain display. Details can be found at
+[MyST documentation](https://myst-parser.readthedocs.io/en/latest/syntax/code_and_apis.html).