Docs: Fix Sphinx build warnings and treat warnings as errors

.readthedocs.yaml

@@ -16,7 +16,7 @@ sphinx:
   # You can configure Sphinx to use a different builder, for instance use the dirhtml builder for simpler URLs
   # builder: "dirhtml"
   # Fail on all warnings to avoid broken references
-  # fail_on_warning: true
+  fail_on_warning: true
 
 # Optionally build your docs in additional formats such as PDF and ePub
 formats: all

docs/CONTRIBUTING.md

@@ -95,7 +95,7 @@ To help us reproduce and confirm a bug, please provide a test case and building
 ## Agent governance and automated review
 
 Before coding or requesting review, read the repository governance entry point
-[`AGENTS.md`](../AGENTS.md) and the full
+[`AGENTS.md`](https://github.com/deepmodeling/abacus-develop/blob/develop/AGENTS.md) and the full
 [ABACUS Agent Governance](./developers_guide/agent_governance.md) guide.
 These rules apply to human contributors, AI agents, GitHub CI, and CodeRabbit.
 

docs/Makefile

@@ -3,7 +3,7 @@
 
 # You can set these variables from the command line, and also
 # from the environment for the first two.
-SPHINXOPTS    ?=
+SPHINXOPTS    ?= -W -n --keep-going
 SPHINXBUILD   ?= sphinx-build
 SOURCEDIR     = $(PWD)
 BUILDDIR      = build

docs/advanced/elec_properties/Mulliken.md

@@ -1,7 +1,7 @@
 # Mulliken Charge Analysis
 
 From version 2.1.0, ABACUS has the function of Mulliken population analysis. The example can be found in [examples/mulliken](https://github.com/deepmodeling/abacus-develop/tree/develop/examples/mulliken). \
-To use this function, set [out_mul](./input-main.md#out_mul) to `1` in the INPUT file. After calculation, there will be an output file named `mulliken.txt` in the output directory. In MD calculations, the output interval is controlled by the keyword [out_freq_ion](./input-main.md#out_freq_ion). In the file, there are contents like (`nspin 1`):
+To use this function, set [out_mul](../input_files/input-main.md#out_mul) to `1` in the INPUT file. After calculation, there will be an output file named `mulliken.txt` in the output directory. In MD calculations, the output interval is controlled by the keyword [out_freq_ion](../input_files/input-main.md#out_freq_ion). In the file, there are contents like (`nspin 1`):
 
 ```
 STEP: 0

docs/advanced/elec_properties/index.rst

@@ -11,4 +11,5 @@ Electronic Properties and Outputs
    charge
    hs_matrix
    density_matrix
+   position_matrix
    Berry_phase

docs/advanced/elec_properties/wfc.md

@@ -14,7 +14,7 @@ The files are stored in `OUT.${suffix}/`. Their pattern is `wfk{k}[s{spin}][g{ge
 
 With `out_freq_ion=0`, files are written only when the electronic calculation converges or reaches `scf_nmax`, and the names contain neither `g*` nor `e*`. During structural relaxation or molecular dynamics, each later ionic step overwrites the same files. With `out_freq_ion>0`, output is restricted to the ionic steps selected by `out_freq_ion` and occurs at multiples of `out_freq_elec`, at convergence, or at `scf_nmax`; both `g*` and `e*` are included in the file names. A static `calculation=scf` or `calculation=nscf` run also receives `g1e*` indices when `out_freq_ion>0`.
 
-The [`init_wfc file binary`](../scf/initialization.md#wave-function) path reads only unindexed binary `wf*_pw.dat` files from `read_file_dir`. Generate directly reusable files with `out_wfc_pw=2` and normally `out_freq_ion=0`. Text `wf*_pw.txt` files and files containing `g*` or `e*` indices are not matched automatically.
+The [`init_wfc file binary`](../scf/initialization.md#wavefunction) path reads only unindexed binary `wf*_pw.dat` files from `read_file_dir`. Generate directly reusable files with `out_wfc_pw=2` and normally `out_freq_ion=0`. Text `wf*_pw.txt` files and files containing `g*` or `e*` indices are not matched automatically.
 
 For `basis_type=lcao`, [`out_wfc_lcao`](https://abacus-rtd.readthedocs.io/en/latest/advanced/input_files/input-main.html#out-wfc-lcao) controls the output of numerical-atomic-orbital coefficients: `1` writes text files with the `.txt` suffix and `2` writes binary files with the `.dat` suffix. Multi-k calculations generate `wfs{spin}k{k-point}_nao.txt` or `.dat`, while Gamma-only calculations generate `wfs{spin}_nao.txt` or `.dat`.
 

docs/advanced/input_files/input-main.md

@@ -3800,7 +3800,7 @@
 
 ### cal_syns
 
-- **Type**: Boolean [Integer](optional)
+- **Type**: Boolean \[Integer\](optional)
 - **Description**: Whether to calculate and output asynchronous overlap matrix for Hefei-NAMD interface. When enabled, calculates <phi(t-1)|phi(t)> by computing overlap between basis functions at atomic positions from previous time step and current time step. The overlap is calculated by shifting atom positions backward by velocity x md_dt. Output file: OUT.*/syns_nao.csr in CSR format.
 
   - 0 or false: disable

docs/advanced/input_files/stru.md

@@ -4,13 +4,13 @@
   - [no latname](#no-latname)
   - [latname fcc](#latname-fcc)
 - [Structure of the file](#structure-of-the-file)
-  - [ATOMIC_SPECIES](#ATOMIC_SPECIES)
-  - [NUMERICAL_ORBITAL](#NUMERICAL_ORBITAL)
-  - [LATTICE_CONSTANT](#LATTICE_CONSTANT)
-  - [LATTICE_VECTORS](#LATTICE_VECTORS)
-  - [LATTICE_PARAMETERS](#LATTICE_PARAMETERS)
-  - [ATOMIC_POSITIONS](#ATOMIC_POSITIONS)
-  - [More Key Words](#More-Key-Words)
+  - [ATOMIC_SPECIES](#atomic_species)
+  - [NUMERICAL_ORBITAL](#numerical_orbital)
+  - [LATTICE_CONSTANT](#lattice_constant)
+  - [LATTICE_VECTORS](#lattice_vectors)
+  - [LATTICE_PARAMETERS](#lattice_parameters)
+  - [ATOMIC_POSITIONS](#atomic_positions)
+  - [More Key Words](#more-key-words)
 
 ## Examples
 

docs/advanced/install.md

@@ -287,7 +287,7 @@ When `CXX=mpicxx`, a parallel version will be compiled. When `CXX=g++`, a sequen
 
 Except modifying `Makefile.vars`, you can also directly use
 
-```makefile
+```bash
 make CXX=mpiicpc ELPA_DIR=/public/soft/elpa_21.05.002 \
 ELPA_INCLUDE_DIR=${ELPA_DIR}/include/elpa-2021.05.002 \
 CEREAL_DIR=/public/soft/cereal
@@ -305,7 +305,7 @@ The program compiled using the above instructions do not link with LIBXC and use
 
 To compile ABACUS with LIBXC, you need to define `LIBXC_DIR` in the file `Makefile.vars` or use
 
-```makefile
+```bash
 make LIBXC_DIR=/pulic/soft/libxc
 ```
 
@@ -315,7 +315,7 @@ directly.
 
 To compile ABACUS with machine learning algorithms, you need to set `ENABLE_MLALGO = ON`, and define `LIBTORCH_DIR` and `LIBNPY_DIR` in the file `Makefile.vars` or use
 
-```makefile
+```bash
 make ENABLE_MLALGO=ON LIBTORCH_DIR=/opt/libtorch/ LIBNPY_DIR=/opt/libnpy/
 ```
 
@@ -329,22 +329,22 @@ directly.
 To compile ABACUS with DeePMD-kit, you need to define `DeePMD_DIR` and `TensorFlow_DIR` (TensorFlow Backend, optional) and/or `LIBTORCH_DIR` (PyTorch Backend, optional) in the file `Makefile.vars`.
 
 Or the `tensorflow_cc` and `torch` libraries are in the same directory as the `deepmd_c`/`deepmd_cc` libraries, then
-```makefile
+```bash
 make DeePMD_DIR=/dir_to_deepmd-kit
 ```
 DeePMD-kit supports TensorFlow backend but its libraries are placed at another directory, then
 
-```makefile
+```bash
 make DeePMD_DIR=/dir_to_deepmd-kit TensorFlow_DIR=/dir_to_tensorflow
 ```
 Similarly, DeePMD-kit supports PyTorch backend but its libraries are placed at another directory, then
-```makefile
+```bash
 make DeePMD_DIR=/dir_to_deepmd-kit Torch_DIR=/dir_to_pytorch
 ```
 
 ### Add LibRI Support
 To use new EXX, you need two libraries: [LibRI](https://github.com/abacusmodeling/LibRI) and [LibComm](https://github.com/abacusmodeling/LibComm) and need to define `LIBRI_DIR` and `LIBCOMM_DIR` in the file `Makefile.vars` or use
-```makefile
+```bash
 make LIBRI_DIR=/public/software/LibRI LIBCOMM_DIR=/public/software/LibComm
 ```
 directly.

docs/advanced/interface/dpgen.md

@@ -14,7 +14,7 @@ Secondly, for the "dpgen init_bulk" step, an `init.json` file should be provided
 
 ```json
 {
-    "init_fp_style":    "ABACUS",   # abacus interface
+    "init_fp_style":    "ABACUS",
     "stages":           [1,2,3,4],
     "cell_type":        "fcc",
     "super_cell":       [2, 1, 1],
@@ -49,7 +49,7 @@ Next, for the "dpgen run" step, the following `run_param.json` should be provide
     "init_data_sys": [
         "Al.STRU.01x01x01/02.md/sys-0004/deepmd"
     ],
-    "sys_format": "abacus/stru",   # the initial structures are in ABACUS/STRU formate
+    "sys_format": "abacus/stru",
     "sys_configs_prefix": "./",
     "sys_configs": [
         [
@@ -162,11 +162,11 @@ Next, for the "dpgen run" step, the following `run_param.json` should be provide
     "fp_task_max": 20,
     "fp_task_min": 5,
     "fp_pp_path": "./",
-    "fp_pp_files": ["Al_ONCV_PBE-1.0.upf"],   # the pseudopotential file
-    "fp_orb_files": ["Al_gga_9au_100Ry_4s4p1d.orb"],  # the orbital file (use only in LCAO calculation)
-    "k_points":[2, 2, 2, 0, 0, 0],  # k-mesh setting
-    "user_fp_params":{  # All the ABACUS input paramters are defined here
-    "ntype": 1,         # defining input parameters from INPUT files is not supported yet.
+    "fp_pp_files": ["Al_ONCV_PBE-1.0.upf"],
+    "fp_orb_files": ["Al_gga_9au_100Ry_4s4p1d.orb"],
+    "k_points":[2, 2, 2, 0, 0, 0],
+    "user_fp_params":{
+    "ntype": 1,
     "ecutwfc": 80,      
     "mixing_type": "broyden",
     "mixing_beta": 0.8,
@@ -176,12 +176,22 @@ Next, for the "dpgen run" step, the following `run_param.json` should be provide
     "smearing_method": "mp",
     "smearing_sigma": 0.002,
     "scf_thr":1e-8,
-    "cal_force":1,        # calculate force must be set to 1 in dpgen calculation
-    "kspacing": 0.01  # when KSPACING is set, the above k_points setting becomes invalid.
+    "cal_force":1,
+    "kspacing": 0.01
     }
 }
 ```
 
+```{important}
+Some ABACUS-specific parameters in this example require additional attention:
+
+- `sys_format`: Set to `"abacus/stru"` when the initial structures are provided in the ABACUS `STRU` format.
+- `fp_orb_files`: Orbital files are required only for LCAO calculations.
+- `user_fp_params`: ABACUS input parameters for first-principles calculations are specified here; specifying them through an `INPUT` file is not supported.
+- `cal_force`: Must be set to `1` for DP-GEN calculations.
+- `k_points` and `kspacing`: `k_points` specifies the k-point mesh. If `kspacing` is set in `user_fp_params`, it takes precedence over `k_points`.
+```
+
 ## autotest
 
 This example can be found in examples/dpgen-example/autotest directory.

docs/advanced/interface/index.rst

@@ -19,3 +19,4 @@ Interfaces to Other Softwares
    ShengBTE
    candela
    TB2J
+   migration-guide-csr-format

docs/advanced/interface/migration-guide-csr-format.md

@@ -1,10 +1,10 @@
-# Migration Guide: New CSR Format for H(R) and S(R) Matrices
+# Migration Guide: New CSR Format for H\(R\) and S\(R\) Matrices
 
 ## Overview
 
-Starting from ABACUS v3.9.0.25, the output format for Hamiltonian H(R) and overlap S(R) matrices has been unified to use standard CSR (Compressed Sparse Row) format, matching the format used by `out_dmr` for density matrices.
+Starting from ABACUS v3.9.0.25, the output format for Hamiltonian H\(R\) and overlap S\(R\) matrices has been unified to use standard CSR (Compressed Sparse Row) format, matching the format used by `out_dmr` for density matrices.
 
-This change affects downstream tools that read H(R) and S(R) matrices, including:
+This change affects downstream tools that read H\(R\) and S\(R\) matrices, including:
 - TB2J (magnetic exchange parameters)
 - DeepH (machine learning Hamiltonian)
 - pyATB (tight-binding analysis)

docs/advanced/json/index.rst

@@ -0,0 +1,7 @@
+=================================================
+JSON Usage
+=================================================
+
+.. toctree::
+   json_add
+   json_para

docs/advanced/md.md

@@ -30,7 +30,7 @@ Furthermore, ABACUS also provides a [list of keywords](./input_files/input-main.
 
 The MD output information will be written into the file `MD_dump`， in which the atomic forces, atomic velocities, and lattice virial are controlled by keyword [dump_force](./input_files/input-main.md#dump_force), [dump_vel](./input_files/input-main.md#dump_vel), and [dump_virial](./input_files/input-main.md#dump_virial), respectively.
 
-[Examples](../../examples/md/lcao_gammaonly_Si8/) of MD simulations are also provided.
+[Examples](https://github.com/deepmodeling/abacus-develop/tree/develop/examples/md/lcao_gammaonly_Si8) of MD simulations are also provided.
 There are eight INPUT files corresponding to eight different MD evolution methods in the directory.
 For examlpe, `INPUT_0` shows how to employ the NVE simulation.
 

docs/advanced/output_files/running_scf.log.md

@@ -1,6 +1,6 @@
 # The running_scf.log file
 
-- [The running\_scf.log file](#the-running_scf.log-file)
+- [The running\_scf.log file](#the-running_scflog-file)
   - [Reading information](#reading-information)
     - [Reading version information](#reading-version-information)
     - [Reading general information](#reading-general-information)

docs/advanced/pp_orb.md

@@ -76,11 +76,10 @@ When performing spin-orbit coupling (SOC) calculations with `lspinorb=1`, specif
 Full-relativistic pseudopotentials suitable for SOC calculations can be identified by checking the UPF file header (`PP_HEADER` section):
 
 ```xml
+<!-- Other attributes omitted -->
 <PP_HEADER
-   ...
    relativistic="full"
    has_so="T"
-   ...
 />
 ```
 

docs/advanced/scf/construct_H.md

@@ -4,7 +4,7 @@
 
 In our package, the XC functional can be set explicitly using the `dft_functional` keyword in `INPUT` file. If `dft_functional` is not specified, ABACUS will use the xc functional indicated in the pseudopotential file. 
 
-Several common functionals are implemented in ABACUS, such as PZ and PBE. Users can check out this [file](../../../source/source_hamilt/module_xc/xc_funcs.h) for a complete list of functionals implemented in ABACUS. Furthermore, if ABACUS is compiled with LIBXC, we also support all the LDA, GGA and meta-GGA functionals provided therein.
+Several common functionals are implemented in ABACUS, such as PZ and PBE. Users can check out this [file](https://github.com/deepmodeling/abacus-develop/blob/develop/source/source_hamilt/module_xc/xc_funcs.h) for a complete list of functionals implemented in ABACUS. Furthermore, if ABACUS is compiled with LIBXC, we also support all the LDA, GGA and meta-GGA functionals provided therein.
 
 Here, we use a simple [example calculation](https://github.com/deepmodeling/abacus-develop/tree/develop/examples/scf/lcao_Si2) for illustration.
 
@@ -69,7 +69,7 @@ Here, we use a simple [example calculation](https://github.com/deepmodeling/abac
 
     ABACUS supports functionals with exact Hartree-Fock exchange in LCAO basis set only. The old INPUT parameter exx_hybrid_type for hybrid functionals has been absorbed into `dft_functional`. Options are `hf` (pure Hartree-Fock), `pbe0`(PBE0), `hse`, and `scan0`(SCAN0) (Note: in order to use HSE or SCAN0 functional, LIBXC is required). Note also that only HSE has been tested while other hybrid functionals have NOT been fully tested yet, and the maximum parallel cpus for running exx is N^4, with N being the number of atoms.
 
-    More information on the hybrid functional can be found from the section [Exact Exchange](../input_files/input-main.md#exact-exchange) in the list of input variables for more information.
+    More information on the hybrid functional can be found from the section [Exact Exchange](../input_files/input-main.md#exact-exchange-common) in the list of input variables for more information.
 
     An example HSE calculation is provided in this [directory](https://github.com/deepmodeling/abacus-develop/tree/develop/examples/hse/lcao_Si2). Apart from the input files (`INPUT`, `STRU`, `KPT`), we further provide two files: running_scf.log_ref and log_ref, which contains reference for running_scf.log and standard output from the program, respectively.
 

docs/advanced/scf/performance.md

@@ -20,7 +20,7 @@ Inclusion of k-point symmetry helps increasing the efficiency of calculations by
 
 For LCAO calculation, the matrix elements of the local potential is evaluated using grid integration. In grid integration, we group real-space FFT grid points into boxes of dimension bx * by * bz, and then proceed with the boxes as the basis unit of calculation.
 
-Setting [bx, by, bz](../input_files/input-main.md#bx-by-bz) to be values other than default might help with the efficiency of grid integration.
+Setting [bx](../input_files/input-main.md#bx), [by](../input_files/input-main.md#by), and [bz](../input_files/input-main.md#bz) to values other than default might help with the efficiency of grid integration.
 
 > Note: the choice of bx, by, bz should be integer factors of the dimension of the real space FFT grid in each direction.
 

docs/community/contribution_guide.md

@@ -11,7 +11,7 @@ We assume you already have a good idea on what to do, otherwise the [issue track
 It is suggested to [submit new issues](https://github.com/deepmodeling/abacus-develop/issues/new/choose) before coding out changes to involve more discussions and suggestions from development team. Refer to the technical guide in [Contributing to ABACUS](../CONTRIBUTING.md) when needed.
 
 - **Follow governance rules.**
-Before implementation and review, read [`AGENTS.md`](../../AGENTS.md) and the
+Before implementation and review, read [`AGENTS.md`](https://github.com/deepmodeling/abacus-develop/blob/develop/AGENTS.md) and the
 [ABACUS Agent Governance](../developers_guide/agent_governance.md) guide. New
 code is reviewed against the shared rules for global dependencies, default
 parameters, header dependencies, tests, INPUT documentation linkage, LF line

docs/conf.py

@@ -50,6 +50,7 @@
     "tasklist",
 ]
 myst_heading_anchors = 4
+nitpicky = True
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']

docs/index.rst

@@ -45,6 +45,7 @@ the developments and applications of novel machine-learning-assisted DFT methods
    advanced/interface/index
    advanced/input_files/index
    advanced/windows_installer
+   advanced/json/index
 
 .. toctree::
    :maxdepth: 2

docs/parameters.yaml

@@ -1780,7 +1780,7 @@ parameters:
     availability: ""
   - name: cal_syns
     category: Molecular dynamics
-    type: "Boolean [Integer](optional)"
+    type: "Boolean \\[Integer\\](optional)"
     description: |
       Whether to calculate and output asynchronous overlap matrix for Hefei-NAMD interface. When enabled, calculates <phi(t-1)|phi(t)> by computing overlap between basis functions at atomic positions from previous time step and current time step. The overlap is calculated by shifting atom positions backward by velocity x md_dt. Output file: OUT.*/syns_nao.csr in CSR format.