docs: regenerate INPUT parameter docs in RTD build

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

@@ -22,9 +22,10 @@ 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 or documentation changes, require updates to the
+  relevant C++ `Input_Item` registration. The parameter YAML stream and
+  `docs/advanced/input_files/input-main.md` are generated transiently during
+  documentation builds and are not stored in the repository.
 - 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,33 +121,18 @@ jobs:
           ccache --show-stats
           ccache --show-stats >> "${GITHUB_STEP_SUMMARY}"
 
-      - name: Check documentation consistency
+      - name: Check INPUT documentation generation
         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
+          # Verify the INPUT reference can be generated from C++ Input_Item definitions
           pip install -q pyyaml
-          python docs/generate_input_main.py \
-            /tmp/parameters_generated.yaml \
+          ${ABACUS_BIN} --generate-parameters-yaml \
+            | python docs/generate_input_main.py - \
             --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"
+          test -s /tmp/input-main-generated.md
+          echo "  INPUT reference generation: OK"
 
       - name: Integrated Tests Preparation
         env:

.gitignore

@@ -29,3 +29,5 @@ toolchain/abacus_env.sh
 .trae
 .codex
 compile_commands.json
+# Generated by the Sphinx INPUT documentation hook.
+/docs/advanced/input_files/input-main.md

.readthedocs.yaml

@@ -9,6 +9,39 @@ build:
   os: ubuntu-22.04
   tools:
     python: "3.11"
+  apt_packages:
+    - build-essential
+    - cmake
+    - gfortran
+    - git
+    - libfftw3-dev
+    - liblapack-dev
+    - libopenblas-dev
+    - ninja-build
+    - pkg-config
+  jobs:
+    pre_build:
+      - >
+        cmake -S . -B build-rtd-docs -G Ninja
+        -DCMAKE_BUILD_TYPE=Release
+        -DENABLE_MPI=OFF
+        -DENABLE_LCAO=OFF
+        -DUSE_OPENMP=OFF
+        -DUSE_ELPA=OFF
+        -DUSE_CUDA=OFF
+        -DUSE_ROCM=OFF
+        -DBUILD_TESTING=OFF
+        -DENABLE_LIBXC=OFF
+        -DENABLE_LIBRI=OFF
+        -DENABLE_DFTD4=OFF
+        -DENABLE_RAPIDJSON=OFF
+        -DENABLE_MLALGO=OFF
+        -DENABLE_FLOAT_FFTW=OFF
+        -DENABLE_CNPY=OFF
+        -DCOMMIT_INFO=OFF
+        -DGIT_SUBMODULE=OFF
+        -DMKLROOT=OFF
+      - cmake --build build-rtd-docs --target abacus_pw_ser --parallel 2
 
 # Build documentation in the "docs/" directory with Sphinx
 sphinx:

AGENTS.md

@@ -53,9 +53,10 @@ 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.
+- INPUT parameter behavior and documentation changes must update the relevant
+  C++ `Input_Item` registration. The parameter YAML stream and
+  `docs/advanced/input_files/input-main.md` are generated transiently during
+  documentation builds and are not stored in the repository.
 - 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
@@ -71,9 +72,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 parsing and help metadata live under `source/source_io/`; Sphinx
+  generates the user-facing INPUT reference 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/CONTRIBUTING.md

@@ -174,40 +174,36 @@ 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. Sphinx generates `docs/advanced/input_files/input-main.md` from an ABACUS executable during every documentation build. The generated YAML stream and Markdown file are not stored in the repository.
 
 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 INPUT Documentation Changes
 
-You **must** regenerate `docs/parameters.yaml` whenever you:
+Update the relevant C++ `Input_Item` registration 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:
+After building ABACUS, preview the generated reference with:
 
 ```bash
-abacus --generate-parameters-yaml > docs/parameters.yaml
+abacus --generate-parameters-yaml \
+  | python3 docs/generate_input_main.py - \
+      --output /tmp/input-main.md
 ```
 
-Then verify the YAML is valid:
+You can also let Sphinx refresh the page during a documentation build:
 
 ```bash
-python3 -c "import yaml; d=yaml.safe_load(open('docs/parameters.yaml')); print(len(d['parameters']), 'parameters')"
+ABACUS_BINARY=/path/to/abacus sphinx-build -b html docs build-docs/html
 ```
 
-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.
+If no ABACUS executable is available, or if generation fails, Sphinx stops with an error. Do not add generated YAML or `input-main.md` files to a commit; update the C++ `Input_Item` registration instead. CI verifies that the reference can be generated successfully.
 
 ### Parameter Documentation Format
 

docs/README.md

@@ -0,0 +1,132 @@
+# ABACUS Documentation
+
+These files are the source for the ABACUS manual published on Read the Docs.
+
+Read the Docs builds a minimal serial ABACUS binary, regenerates
+`docs/advanced/input_files/input-main.md` from that binary during the
+documentation build, and fails the build if the INPUT reference cannot be
+refreshed.
+
+## Build the Manual Locally
+
+Run the following commands from the repository root.
+
+1. Create a Python virtual environment:
+
+   ```bash
+   python3 -m venv .venv
+   source .venv/bin/activate
+   ```
+
+1. Install the Python documentation requirements:
+
+   ```bash
+   pip3 install -r docs/requirements.txt
+   ```
+
+The reduced ABACUS build also requires a C++ compiler, a Fortran compiler,
+CMake, Ninja, FFTW3, BLAS, and LAPACK. These are system/build dependencies,
+not Python documentation dependencies.
+
+1. Build the reduced ABACUS executable used for INPUT parameter metadata:
+
+   ```bash
+   cmake -S . -B build-rtd-docs -G Ninja \
+     -DCMAKE_BUILD_TYPE=Release \
+     -DENABLE_MPI=OFF \
+     -DENABLE_LCAO=OFF \
+     -DUSE_OPENMP=OFF \
+     -DUSE_ELPA=OFF \
+     -DUSE_CUDA=OFF \
+     -DUSE_ROCM=OFF \
+     -DBUILD_TESTING=OFF \
+     -DENABLE_LIBXC=OFF \
+     -DENABLE_LIBRI=OFF \
+     -DENABLE_DFTD4=OFF \
+     -DENABLE_RAPIDJSON=OFF \
+     -DENABLE_MLALGO=OFF \
+     -DENABLE_FLOAT_FFTW=OFF \
+     -DENABLE_CNPY=OFF \
+     -DCOMMIT_INFO=OFF \
+     -DGIT_SUBMODULE=OFF \
+     -DMKLROOT=OFF
+   cmake --build build-rtd-docs --target abacus_pw_ser --parallel 2
+   ```
+
+1. (Optional) Generate the INPUT reference manually for inspection:
+
+   The ABACUS executable emits the parameter metadata as a transient YAML
+   stream. Pipe that stream directly to the Markdown generator; neither
+   `docs/parameters.yaml` nor `docs/advanced/input_files/input-main.md` is
+   maintained in the repository.
+
+   ```bash
+   ./build-rtd-docs/abacus_pw_ser --generate-parameters-yaml \
+     | .venv/bin/python docs/generate_input_main.py - \
+         --output /tmp/input-main.md
+   ```
+
+1. Build the HTML manual:
+
+   ```bash
+   ABACUS_BINARY=./build-rtd-docs/abacus_pw_ser \
+     .venv/bin/sphinx-build -b html docs build-docs/html
+   ```
+
+   If `ABACUS_BINARY` is not set, `docs/conf.py` looks for the Read the Docs
+   build binary and then for `abacus` or `abacus_pw_ser` on `PATH`.
+
+1. Open `build-docs/html/index.html` in a browser.
+
+Every documentation build requires an ABACUS executable. If no executable is
+available, or if parameter generation fails, Sphinx stops with an error rather
+than publishing incomplete or stale INPUT documentation.
+
+## Regenerate Only the INPUT Reference
+
+To refresh only the generated INPUT reference after building ABACUS, pipe the
+transient YAML stream directly into the Markdown generator:
+
+```bash
+./build-rtd-docs/abacus_pw_ser --generate-parameters-yaml \
+  | .venv/bin/python docs/generate_input_main.py - \
+      --output /tmp/input-main.md
+```
+
+## INPUT Parameter Reference
+
+The INPUT parameter reference is generated from metadata registered in
+`source/source_io/module_parameter/read_input_item_*.cpp`.
+
+- `abacus --generate-parameters-yaml` produces a transient YAML stream; it is
+  not stored in the repository.
+- `docs/advanced/input_files/input-main.md` is generated from that metadata
+  during every Sphinx build and is not stored in the repository.
+- `docs/conf.py` requires an ABACUS executable and fails the build if the INPUT
+  reference cannot be generated.
+
+PRs that change INPUT metadata only update the C++ `Input_Item` registrations.
+The YAML stream and Markdown reference are both transient build artifacts.
+
+## Optional Read the Docs Container Test
+
+To smoke-test the Read the Docs environment locally, use the same image as the
+hosted build:
+
+```bash
+docker run --rm --user root -v "$PWD:/project" -w /project \
+  readthedocs/build:ubuntu-22.04-2024.01.29 \
+  /bin/bash -lc 'apt-get update &&
+  apt-get install -y build-essential cmake gfortran git libfftw3-dev \
+    liblapack-dev libopenblas-dev ninja-build pkg-config python3-pip &&
+  python3 -m pip install -r docs/requirements.txt &&
+  cmake -S . -B /tmp/build-rtd-docs -G Ninja -DCMAKE_BUILD_TYPE=Release \
+    -DENABLE_MPI=OFF -DENABLE_LCAO=OFF -DUSE_OPENMP=OFF -DUSE_ELPA=OFF \
+    -DUSE_CUDA=OFF -DUSE_ROCM=OFF -DBUILD_TESTING=OFF \
+    -DENABLE_LIBXC=OFF -DENABLE_LIBRI=OFF -DENABLE_DFTD4=OFF \
+    -DENABLE_RAPIDJSON=OFF -DENABLE_MLALGO=OFF -DENABLE_FLOAT_FFTW=OFF \
+    -DENABLE_CNPY=OFF -DCOMMIT_INFO=OFF -DGIT_SUBMODULE=OFF -DMKLROOT=OFF &&
+  cmake --build /tmp/build-rtd-docs --target abacus_pw_ser --parallel 2 &&
+  export READTHEDOCS=True ABACUS_BINARY=/tmp/build-rtd-docs/abacus_pw_ser &&
+  sphinx-build -b html docs /tmp/abacus-docs-html'
+```