Docs: Handle sphinx build warnings and treat warnings as error

[Growl1234]

Here are the warnings generated when running make html. Since most programs use -W flags in their sphinx-build Makefiles which means treating all warnings as errors, I think we should think of these warnings as relevant. After fixing all these warnings, we should finally add -W to SPHINXOPTS to prevent such cases to happen again.

...
checking consistency... /root/GitHub/abacus-dev/docs/advanced/elec_properties/position_matrix.md: WARNING: document isn't included in any toctree [toc.not_included]
/root/GitHub/abacus-dev/docs/advanced/interface/migration-guide-csr-format.md: WARNING: document isn't included in any toctree [toc.not_included]
/root/GitHub/abacus-dev/docs/advanced/json/json_add.md: WARNING: document isn't included in any toctree [toc.not_included]
/root/GitHub/abacus-dev/docs/advanced/json/json_para.md: WARNING: document isn't included in any toctree [toc.not_included]
...
/root/GitHub/abacus-dev/docs/CONTRIBUTING.md:97: WARNING: Unknown source document '/root/GitHub/abacus-dev/AGENTS' [myst.xref_missing] [myst.xref_missing]
/root/GitHub/abacus-dev/docs/advanced/elec_properties/Mulliken.md:3: WARNING: 'myst' cross-reference target not found: './input-main.md#out_mul' [myst.xref_missing] [myst.xref_missing]
/root/GitHub/abacus-dev/docs/advanced/elec_properties/Mulliken.md:3: WARNING: 'myst' cross-reference target not found: './input-main.md#out_freq_ion' [myst.xref_missing] [myst.xref_missing]
/root/GitHub/abacus-dev/docs/advanced/elec_properties/wfc.md:17: WARNING: local id not found in doc 'advanced/scf/initialization': 'wave-function' [myst.xref_missing] [myst.xref_missing]
/root/GitHub/abacus-dev/docs/advanced/input_files/input-main.md:3767: WARNING: 'myst' cross-reference target not found: 'optional' [myst.xref_missing] [myst.xref_missing]
/root/GitHub/abacus-dev/docs/advanced/input_files/stru.md:7: WARNING: 'myst' cross-reference target not found: 'ATOMIC_SPECIES' [myst.xref_missing] [myst.xref_missing]
/root/GitHub/abacus-dev/docs/advanced/input_files/stru.md:8: WARNING: 'myst' cross-reference target not found: 'NUMERICAL_ORBITAL' [myst.xref_missing] [myst.xref_missing]
/root/GitHub/abacus-dev/docs/advanced/input_files/stru.md:9: WARNING: 'myst' cross-reference target not found: 'LATTICE_CONSTANT' [myst.xref_missing] [myst.xref_missing]
/root/GitHub/abacus-dev/docs/advanced/input_files/stru.md:10: WARNING: 'myst' cross-reference target not found: 'LATTICE_VECTORS' [myst.xref_missing] [myst.xref_missing]
/root/GitHub/abacus-dev/docs/advanced/input_files/stru.md:11: WARNING: 'myst' cross-reference target not found: 'LATTICE_PARAMETERS' [myst.xref_missing] [myst.xref_missing]
/root/GitHub/abacus-dev/docs/advanced/input_files/stru.md:12: WARNING: 'myst' cross-reference target not found: 'ATOMIC_POSITIONS' [myst.xref_missing] [myst.xref_missing]
/root/GitHub/abacus-dev/docs/advanced/input_files/stru.md:13: WARNING: 'myst' cross-reference target not found: 'More-Key-Words' [myst.xref_missing] [myst.xref_missing]
/root/GitHub/abacus-dev/docs/advanced/install.md:286: WARNING: Lexing literal_block 'make CXX=mpiicpc ELPA_DIR=/public/soft/elpa_21.05.002 \\\nELPA_INCLUDE_DIR=${ELPA_DIR}/include/elpa-2021.05.002 \\\nCEREAL_DIR=/public/soft/cereal\n' as "makefile" resulted in an error at token: 'm'. Retrying in relaxed mode. [misc.highlighting_failure]
/root/GitHub/abacus-dev/docs/advanced/install.md:304: WARNING: Lexing literal_block 'make LIBXC_DIR=/pulic/soft/libxc\n' as "makefile" resulted in an error at token: 'm'. Retrying in relaxed mode. [misc.highlighting_failure]
/root/GitHub/abacus-dev/docs/advanced/install.md:314: WARNING: Lexing literal_block 'make ENABLE_MLALGO=ON LIBTORCH_DIR=/opt/libtorch/ LIBNPY_DIR=/opt/libnpy/\n' as "makefile" resulted in an error at token: 'm'. Retrying in relaxed mode. [misc.highlighting_failure]
/root/GitHub/abacus-dev/docs/advanced/install.md:328: WARNING: Lexing literal_block 'make DeePMD_DIR=/dir_to_deepmd-kit\n' as "makefile" resulted in an error at token: 'm'. Retrying in relaxed mode. [misc.highlighting_failure]
/root/GitHub/abacus-dev/docs/advanced/install.md:333: WARNING: Lexing literal_block 'make DeePMD_DIR=/dir_to_deepmd-kit TensorFlow_DIR=/dir_to_tensorflow\n' as "makefile" resulted in an error at token: 'm'. Retrying in relaxed mode. [misc.highlighting_failure]
/root/GitHub/abacus-dev/docs/advanced/install.md:337: WARNING: Lexing literal_block 'make DeePMD_DIR=/dir_to_deepmd-kit Torch_DIR=/dir_to_pytorch\n' as "makefile" resulted in an error at token: 'm'. Retrying in relaxed mode. [misc.highlighting_failure]
/root/GitHub/abacus-dev/docs/advanced/install.md:343: WARNING: Lexing literal_block 'make LIBRI_DIR=/public/software/LibRI LIBCOMM_DIR=/public/software/LibComm\n' as "makefile" resulted in an error at token: 'm'. Retrying in relaxed mode. [misc.highlighting_failure]
/root/GitHub/abacus-dev/docs/advanced/interface/dpgen.md:15: WARNING: Lexing literal_block '{\n    "init_fp_style":    "ABACUS",   # abacus interface\n    "stages":           [1,2,3,4],\n    "cell_type":        "fcc",\n    "super_cell":       [2, 1, 1],\n    "elements":         ["Al"],\n    "from_poscar":      true,\n    "from_poscar_path": "./Al.STRU",\n    "potcars":          ["Al_ONCV_PBE-1.0.upf"],\n    "relax_incar":      "INPUT",\n    "relax_kpt":        "KPT",\n    "md_incar" :        "INPUT.md",\n    "md_kpt" :          "KPT",\n    "skip_relax":       false,\n    "scale":            [1.00],\n    "pert_numb":        10,\n    "pert_box":         0.01,\n    "pert_atom":        0.01,\n    "coll_ndata":       10,\n    "_comment":         "that\'s all"\n}\n' as "json" resulted in an error at token: '#'. Retrying in relaxed mode. [misc.highlighting_failure]
/root/GitHub/abacus-dev/docs/advanced/interface/dpgen.md:40: WARNING: Lexing literal_block '{\n    "type_map": [\n        "Al"\n    ],\n    "mass_map": [\n        26.9815\n    ],\n    "init_data_prefix": "./",\n    "init_data_sys": [\n        "Al.STRU.01x01x01/02.md/sys-0004/deepmd"\n    ],\n    "sys_format": "abacus/stru",   # the initial structures are in ABACUS/STRU formate\n    "sys_configs_prefix": "./",\n    "sys_configs": [\n        [\n            "Al.STRU.01x01x01/01.scale_pert/sys-0004/scale*/00000*/STRU" \n        ],\n        [\n            "Al.STRU.01x01x01/01.scale_pert/sys-0004/scale*/000010/STRU" \n        ]\n    ],\n    "_comment": " 00.train ",\n    "numb_models": 4,\n    "default_training_param": {\n        "model": {\n            "type_map": [\n                "Al"\n            ],\n            "descriptor": {\n                "type": "se_e2_a",\n                "sel": [\n                    16\n                ],\n                "rcut_smth": 0.5,\n                "rcut": 5.0,\n                "neuron": [\n                    10,\n                    20,\n                    40\n                ],\n                "resnet_dt": true,\n                "axis_neuron": 12,\n                "seed": 1\n            },\n            "fitting_net": {\n                "neuron": [\n                    25,\n                    50,\n                    100\n                ],\n                "resnet_dt": false,\n                "seed": 1\n            }\n        },\n        "learning_rate": {\n            "type": "exp",\n            "start_lr": 0.001,\n            "decay_steps": 100\n        },\n        "loss": {\n            "start_pref_e": 0.02,\n            "limit_pref_e": 2,\n            "start_pref_f": 1000,\n            "limit_pref_f": 1,\n            "start_pref_v": 0.0,\n            "limit_pref_v": 0.0\n        },\n        "training": {\n            "stop_batch": 20000,\n            "disp_file": "lcurve.out",\n            "disp_freq": 1000,\n            "numb_test": 4,\n            "save_freq": 1000,\n            "save_ckpt": "model.ckpt",\n            "disp_training": true,\n            "time_training": true,\n            "profiling": false,\n            "profiling_file": "timeline.json",\n            "_comment": "that\'s all"\n        }\n    },\n    "_comment": "01.model_devi ",\n    "model_devi_dt": 0.002,\n    "model_devi_skip": 0,\n    "model_devi_f_trust_lo": 0.05,\n    "model_devi_f_trust_hi": 0.15,\n    "model_devi_clean_traj": false,\n    "model_devi_jobs": [\n        {\n            "sys_idx": [\n                0\n            ],\n            "temps": [\n                50\n            ],\n            "press": [\n                1.0\n            ],\n            "trj_freq": 10,\n            "nsteps": 300,\n            "ensemble": "nvt",\n            "_idx": "00"\n        },\n        {\n            "sys_idx": [\n                1\n            ],\n            "temps": [\n                50\n            ],\n            "press": [\n                1.0\n            ],\n            "trj_freq": 10,\n            "nsteps": 3000,\n            "ensemble": "nvt",\n            "_idx": "01"\n        }\n    ],\n    "fp_style": "abacus/scf",\n    "shuffle_poscar": false,\n    "fp_task_max": 20,\n    "fp_task_min": 5,\n    "fp_pp_path": "./",\n    "fp_pp_files": ["Al_ONCV_PBE-1.0.upf"],   # the pseudopotential file\n    "fp_orb_files": ["Al_gga_9au_100Ry_4s4p1d.orb"],  # the orbital file (use only in LCAO calculation)\n    "k_points":[2, 2, 2, 0, 0, 0],  # k-mesh setting\n    "user_fp_params":{  # All the ABACUS input paramters are defined here\n    "ntype": 1,         # defining input parameters from INPUT files is not supported yet.\n    "ecutwfc": 80,      \n    "mixing_type": "broyden",\n    "mixing_beta": 0.8,\n    "symmetry": 1,\n    "nspin": 1,\n    "ks_solver": "cg",\n    "smearing_method": "mp",\n    "smearing_sigma": 0.002,\n    "scf_thr":1e-8,\n    "cal_force":1,        # calculate force must be set to 1 in dpgen calculation\n    "kspacing": 0.01  # when KSPACING is set, the above k_points setting becomes invalid.\n    }\n}\n' as "json" resulted in an error at token: '#'. Retrying in relaxed mode. [misc.highlighting_failure]
/root/GitHub/abacus-dev/docs/advanced/json/json_add.md:11: WARNING: 'myst' cross-reference target not found: '2-json-codes-addition-guidelines' [myst.xref_missing] [myst.xref_missing]
/root/GitHub/abacus-dev/docs/advanced/md.md:33: WARNING: 'myst' cross-reference target not found: '../../examples/md/lcao_gammaonly_Si8/' [myst.xref_missing] [myst.xref_missing]
/root/GitHub/abacus-dev/docs/advanced/output_files/running_scf.log.md:3: WARNING: 'myst' cross-reference target not found: 'the-running_scf.log-file' [myst.xref_missing] [myst.xref_missing]
/root/GitHub/abacus-dev/docs/advanced/pp_orb.md:78: WARNING: Lexing literal_block '<PP_HEADER\n   ...\n   relativistic="full"\n   has_so="T"\n   ...\n/>\n' as "xml" resulted in an error at token: '.'. Retrying in relaxed mode. [misc.highlighting_failure]
/root/GitHub/abacus-dev/docs/advanced/scf/construct_H.md:7: WARNING: 'myst' cross-reference target not found: '../../../source/source_hamilt/module_xc/xc_funcs.h' [myst.xref_missing] [myst.xref_missing]
/root/GitHub/abacus-dev/docs/advanced/scf/construct_H.md:72: WARNING: local id not found in doc 'advanced/input_files/input-main': 'exact-exchange' [myst.xref_missing] [myst.xref_missing]
/root/GitHub/abacus-dev/docs/advanced/scf/performance.md:23: WARNING: local id not found in doc 'advanced/input_files/input-main': 'bx-by-bz' [myst.xref_missing] [myst.xref_missing]
/root/GitHub/abacus-dev/docs/community/contribution_guide.md:13: WARNING: Unknown source document '/root/GitHub/abacus-dev/AGENTS' [myst.xref_missing] [myst.xref_missing]
/root/GitHub/abacus-dev/docs/quick_start/easy_install.md:3: WARNING: 'myst' cross-reference target not found: './advanced/windows_installer.md' [myst.xref_missing] [myst.xref_missing]
/root/GitHub/abacus-dev/docs/quick_start/easy_install.md:274: WARNING: 'myst' cross-reference target not found: '../../Dockerfile' [myst.xref_missing] [myst.xref_missing]
/root/GitHub/abacus-dev/docs/quick_start/input.md:11: WARNING: Pygments lexer name 'plaintext' is not known [misc.highlighting_failure]
/root/GitHub/abacus-dev/docs/quick_start/input.md:106: WARNING: Pygments lexer name 'plaintext' is not known [misc.highlighting_failure]
/root/GitHub/abacus-dev/docs/quick_start/input.md:155: WARNING: Pygments lexer name 'plaintext' is not known [misc.highlighting_failure]
...

[mohanchen]

Good idea! Could you implement the changes?

[Growl1234]

I'm willing to take the jobs. My time is limited these days; most likely it will be done next week.