DeepMD-kit Documentation Builds#
DeepMD-kit's documentation is built on Read the Docs using Sphinx, driven by .readthedocs.yml at the repo root. The build runs on Ubuntu 20.04 (pending upgrade to 26.04 per PR #5392 ), Python 3.11, and uses uv to install dependencies โ replacing the prior Conda-based setup removed in PR #3685 .
Configuration Overview#
The .readthedocs.yml specifies:
| Setting | Value |
|---|---|
| OS | ubuntu-20.04 |
| Python | 3.11 |
| Dep installer | uv (post-create-environment hook) |
| Dependencies | doc/requirements.txt (post-install hook) |
| Sphinx config | doc/conf.py |
| Extra formats | PDF โ removed in PR #5710 to fix timeouts |
The post_install step runs:
VIRTUAL_ENV=$READTHEDOCS_VIRTUALENV_PATH uv pip install -r doc/requirements.txt
doc/requirements.txt installs the project with three extras plus version constraints:
.[docs,cpu,torch]
docutils!=0.18.*,!=0.19.*
sphinx>=7
The docutils pin works around a sphinxcontrib-bibtex bug. The torch extra is required because several documentation modules import PyTorch at build time โ its absence previously caused No module named 'torch' errors (fixed in PR #3333) .
Sphinx Extensions and Docs Stack#
doc/conf.py sets intersphinx_timeout = 30 for external cross-reference inventory requests. This limits connection and read-inactivity waits to 30 seconds so Sphinx can warn and continue if a host stalls; it is not a deadline for a complete inventory download or the entire documentation build.
The docs optional-dependency group in pyproject.toml declares the full Sphinx stack: breathe + exhale for C++ API documentation (from Doxygen), myst-nb / myst-parser for Markdown notebooks, sphinxcontrib-moderncmakedomain for CMake docs, and several DeepModeling-specific extensions (deepmodeling-sphinx, dargs, pygments-lammps).
A legacy doc/environment.yml Conda file also exists , mirroring the same .[docs,cpu,torch] install. It is no longer used by Read the Docs (replaced by doc/requirements.txt in PR #3685) but may be useful for local Conda-based builds.
C++ Standard and PyTorch Compatibility#
The CMake build uses an adaptive C++ standard strategy :
- Default: C++11 (raised to C++14 for full C++ builds)
- PyTorch โฅ 1.5: C++14 minimum
- PyTorch โฅ 2.1: C++17 minimum โ applied via the
set_if_highermacro that only raises the standard, never lowers it - CUDA โฅ 13.0: C++17 minimum
This logic ensures that the project's CMake default (C++11) is automatically bumped when a backend requires a newer standard. The set_if_higher macro prevents any backend from accidentally downgrading the standard set by another.
The C++ standard is relevant to the documentation build only via the exhale/Doxygen API generation step. The RTD job installs the torch CPU extra but does not invoke CMake โ so C++ standard selection is a compile-time, not a docs-build, concern. No C++20 requirement exists in the current documentation build chain; the highest standard any backend demands via CMake is C++17 (PyTorch โฅ 2.1 or CUDA โฅ 13).
Note: PyTorch 2.8 introduced an ABI selection quirk on Linux where
torch.compiled_with_cxx11_abialways returnsTrue, handled separately in CMake at .
Key History#
| PR | Change |
|---|---|
| #3333 | Added torch extra to RTD install to fix No module named 'torch' |
| #3685 | Replaced Conda + environment.yml with uv + requirements.txt; switched to Python 3.11 |
| #3973 | CMake: auto-select C++14/17 based on PyTorch version |
| #5017 | CMake: raise C++ standard to 17 for CUDA โฅ 13 |
| #5392 | RTD: upgrade OS from Ubuntu 20.04 โ 26.04 due to RTD deprecation |
| #5710 | RTD: removed PDF format to fix build timeouts |
Primary Sources#
.readthedocs.ymlโ RTD build configurationdoc/requirements.txtโ Documentation Python dependenciesdoc/environment.ymlโ Legacy Conda environment (for local builds)pyproject.toml(docs extra) โ Full Sphinx extension listsource/CMakeLists.txtโ C++ standard selection logic