docs: document CMake variables using Sphinx styles (deepmodeling#4079)

## Summary by CodeRabbit - **New Features** - Added support for modern CMake projects in documentation through the `sphinxcontrib.moderncmakedomain` extension. - Enhanced installation documentation for DeePMD-kit's C++ interface and source builds, improving clarity and usability. - **Documentation** - Improved formatting and structure of CMake configuration options for better readability and understanding. - Standardized documentation for `DEEPMD_C_ROOT` variable and other CMake options, including links to relevant documentation.  --------- Signed-off-by: Jinzhe Zeng <[email protected]>
njzjz · Aug 27, 2024 · eca75c3 · eca75c3
1 parent af5a937
commit eca75c3
Show file tree

Hide file tree

Showing 4 changed files with 131 additions and 18 deletions.
diff --git a/doc/conf.py b/doc/conf.py
@@ -69,6 +69,7 @@
     "sphinx_design",
     "autoapi.extension",
     "sphinxcontrib.programoutput",
+    "sphinxcontrib.moderncmakedomain",
 ]
 
 # breathe_domain_by_extension = {

diff --git a/doc/install/install-from-c-library.md b/doc/install/install-from-c-library.md
@@ -16,7 +16,7 @@ The library is built in Linux (GLIBC 2.17) with CUDA 12.2 (`libdeepmd_c.tar.gz`)
 
 ## Use Pre-compiled C Library to build the LAMMPS plugin, i-PI driver, and GROMACS patch
 
-When one [installs DeePMD-kit's C++ interface](./install-from-source.md#install-deepmd-kits-c-interface), one can use the CMake argument `DEEPMD_C_ROOT` to the path `libdeepmd_c`.
+When one [installs DeePMD-kit's C++ interface](./install-from-source.md#install-deepmd-kits-c-interface), one can use the CMake argument {cmake:variable}`DEEPMD_C_ROOT` to the path `libdeepmd_c`.
 
 ```bash
 cd $deepmd_source_dir/source
@@ -29,3 +29,11 @@ make install
 
 Then the i-PI driver `dp_ipi` will be built and installed.
 One can also follow the manual [Install LAMMPS](./install-lammps.md) and/or [Install GROMACS](./install-gromacs.md).
+
+:::{cmake:variable} DEEPMD_C_ROOT
+
+**Type**: `Path`
+
+Prefix to the pre-compiled C library.
+
+:::
diff --git a/doc/install/install-from-source.md b/doc/install/install-from-source.md
@@ -353,23 +353,126 @@ cmake -DENABLE_PYTORCH=TRUE -DUSE_PT_PYTHON_LIBS=TRUE -DCMAKE_INSTALL_PREFIX=$de
 
 ::::
 
-One may add the following arguments to `cmake`:
-
-| CMake Aurgements                                                             | Allowed value     | Default value          | Usage                                                                                                                                                                                             |
-| ---------------------------------------------------------------------------- | ----------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| -DENABLE_TENSORFLOW=&lt;value&gt;                                            | `TRUE` or `FALSE` | `FALSE`                | {{ tensorflow_icon }} Whether building the TensorFlow backend.                                                                                                                                    |
-| -DENABLE_PYTORCH=&lt;value&gt;                                               | `TRUE` or `FALSE` | `FALSE`                | {{ pytorch_icon }} Whether building the PyTorch backend.                                                                                                                                          |
-| -DTENSORFLOW_ROOT=&lt;value&gt;                                              | Path              | -                      | {{ tensorflow_icon }} The Path to TensorFlow's C++ interface.                                                                                                                                     |
-| -DCMAKE_INSTALL_PREFIX=&lt;value&gt;                                         | Path              | -                      | The Path where DeePMD-kit will be installed.                                                                                                                                                      |
-| -DUSE_CUDA_TOOLKIT=&lt;value&gt;                                             | `TRUE` or `FALSE` | `FALSE`                | If `TRUE`, Build GPU support with CUDA toolkit.                                                                                                                                                   |
-| -DCUDAToolkit_ROOT=&lt;value&gt;                                             | Path              | Detected automatically | The path to the CUDA toolkit directory. CUDA 9.0 or later is supported. NVCC is required.                                                                                                         |
-| -DUSE_ROCM_TOOLKIT=&lt;value&gt;                                             | `TRUE` or `FALSE` | `FALSE`                | If `TRUE`, Build GPU support with ROCM toolkit.                                                                                                                                                   |
-| -DCMAKE_HIP_COMPILER_ROCM_ROOT=&lt;value&gt;                                 | Path              | Detected automatically | The path to the ROCM toolkit directory.                                                                                                                                                           |
-| -DLAMMPS_SOURCE_ROOT=&lt;value&gt;                                           | Path              | -                      | Only neccessary for LAMMPS plugin mode. The path to the [LAMMPS source code](install-lammps.md). LAMMPS 8Apr2021 or later is supported. If not assigned, the plugin mode will not be enabled.     |
-| -DUSE_TF_PYTHON_LIBS=&lt;value&gt;                                           | `TRUE` or `FALSE` | `FALSE`                | {{ tensorflow_icon }} If `TRUE`, Build C++ interface with TensorFlow's Python libraries (TensorFlow's Python Interface is required). And there's no need for building TensorFlow's C++ interface. |
-| -DUSE_PT_PYTHON_LIBS=&lt;value&gt;                                           | `TRUE` or `FALSE` | `FALSE`                | {{ pytorch_icon }} If `TRUE`, Build C++ interface with PyTorch's Python libraries (PyTorch's Python Interface is required). And there's no need for downloading PyTorch's C++ libraries.          |
-| -DENABLE_NATIVE_OPTIMIZATION=&lt;value&gt;                                   | `TRUE` or `FALSE` | `FALSE`                | Enable compilation optimization for the native machine's CPU type. Do not enable it if generated code will run on different CPUs.                                                                 |
-| -DCMAKE\_&lt;LANG&gt;\_FLAGS=&lt;value&gt; (`<LANG>`=`CXX`, `CUDA` or `HIP`) | str               | -                      | Default compilation flags to be used when compiling `<LANG>` files. See [CMake documentation](https://cmake.org/cmake/help/latest/variable/CMAKE_LANG_FLAGS.html).                                |
+One may add the following CMake variables to `cmake` using the [`-D <var>=<value>` option](https://cmake.org/cmake/help/latest/manual/cmake.1.html#cmdoption-cmake-D):
+
+:::{cmake:variable} ENABLE_TENSORFLOW
+
+**Type**: `BOOL` (`ON`/`OFF`), Default: `OFF`
+
+{{ tensorflow_icon }} Whether building the TensorFlow backend.
+
+:::
+
+:::{cmake:variable} ENABLE_PYTORCH
+
+**Type**: `BOOL` (`ON`/`OFF`), Default: `OFF`
+
+{{ pytorch_icon }} Whether building the PyTorch backend.
+
+:::
+
+:::{cmake:variable} TENSORFLOW_ROOT
+
+**Type**: `PATH`
+
+{{ tensorflow_icon }} The Path to TensorFlow's C++ interface.
+
+:::
+
+:::{cmake:variable} CMAKE_INSTALL_PREFIX
+
+**Type**: `PATH`
+
+The Path where DeePMD-kit will be installed.
+See also [CMake documentation](https://cmake.org/cmake/help/latest/variable/CMAKE_INSTALL_PREFIX.html).
+
+:::
+
+:::{cmake:variable} USE_CUDA_TOOLKIT
+
+**Type**: `BOOL` (`ON`/`OFF`), Default: `OFF`
+
+If `TRUE`, Build GPU support with CUDA toolkit.
+
+:::
+
+:::{cmake:variable} CUDAToolkit_ROOT
+
+**Type**: `PATH`, **Default**: [Search automatically](https://cmake.org/cmake/help/latest/module/FindCUDAToolkit.html)
+
+The path to the CUDA toolkit directory. CUDA 9.0 or later is supported. NVCC is required.
+See also [CMake documentation](https://cmake.org/cmake/help/latest/module/FindCUDAToolkit.html).
+
+:::
+
+:::{cmake:variable} USE_ROCM_TOOLKIT
+
+**Type**: `BOOL` (`ON`/`OFF`), Default: `OFF`
+
+If `TRUE`, Build GPU support with ROCM toolkit.
+
+:::
+
+:::{cmake:variable} CMAKE_HIP_COMPILER_ROCM_ROOT
+
+**Type**: `PATH`, **Default**: [Search automatically](https://rocm.docs.amd.com/en/latest/conceptual/cmake-packages.html)
+
+The path to the ROCM toolkit directory.
+See also [ROCm documentation](https://rocm.docs.amd.com/en/latest/conceptual/cmake-packages.html).
+
+:::
+
+:::{cmake:variable} LAMMPS_SOURCE_ROOT
+
+**Type**: `PATH`
+
+Only neccessary for using [LAMMPS plugin mode](./install-lammps.md#install-lammps-plugin-mode).
+The path to the [LAMMPS source code](install-lammps.md).
+LAMMPS 8Apr2021 or later is supported.
+If not assigned, the plugin mode will not be enabled.
+
+:::
+
+:::{cmake:variable} USE_TF_PYTHON_LIBS
+
+**Type**: `BOOL` (`ON`/`OFF`), Default: `OFF`
+
+{{ tensorflow_icon }} If `TRUE`, Build C++ interface with TensorFlow's Python libraries (TensorFlow's Python Interface is required).
+There's no need for building TensorFlow's C++ interface.
+
+:::
+
+:::{cmake:variable} USE_PT_PYTHON_LIBS
+
+**Type**: `BOOL` (`ON`/`OFF`), Default: `OFF`
+
+{{ pytorch_icon }} If `TRUE`, Build C++ interface with PyTorch's Python libraries (PyTorch's Python Interface is required).
+There's no need for downloading PyTorch's C++ libraries.
+
+:::
+
+:::{cmake:variable} ENABLE_NATIVE_OPTIMIZATION
+
+**Type**: `BOOL` (`ON`/`OFF`), Default: `OFF`
+
+Enable compilation optimization for the native machine's CPU type.
+Do not enable it if generated code will run on different CPUs.
+
+:::
+
+<!-- prettier-ignore -->
+:::{cmake:variable} CMAKE_<LANG>_FLAGS
+
+(`<LANG>`=`CXX`, `CUDA` or `HIP`)
+
+**Type**: `STRING`
+
+Default compilation flags to be used when compiling `<LANG>` files.
+See also [CMake documentation](https://cmake.org/cmake/help/latest/variable/CMAKE_LANG_FLAGS.html).
+
+:::
+
+---
 
 If the CMake has been executed successfully, then run the following make commands to build the package:
 

diff --git a/pyproject.toml b/pyproject.toml
@@ -101,6 +101,7 @@ docs = [
     "sphinxcontrib-bibtex",
     "sphinx-autoapi>=3.0.0",
     "sphinxcontrib-programoutput",
+    "sphinxcontrib-moderncmakedomain",
 ]
 lmp = [
     "lammps~=2023.8.2.3.0",