diff --git a/.readthedocs.yml b/.readthedocs.yml new file mode 100644 index 0000000..9630552 --- /dev/null +++ b/.readthedocs.yml @@ -0,0 +1,13 @@ +version: 2 +build: + os: ubuntu-24.04 + tools: + python: "3.12" + jobs: + install: + - asdf plugin add uv + - asdf install uv latest + - asdf global uv latest + - VIRTUAL_ENV=$READTHEDOCS_VIRTUALENV_PATH uv pip install deepmd-kit[torch]>=3.0.0b2 --extra-index-url https://download.pytorch.org/whl/cpu + - VIRTUAL_ENV=$READTHEDOCS_VIRTUALENV_PATH CMAKE_PREFIX_PATH=$(python -c "import torch;print(torch.utils.cmake_prefix_path)") uv pip install -e .[docs] + - $READTHEDOCS_VIRTUALENV_PATH/bin/python -m sphinx -T -b html -d docs/_build/doctrees -D language=en docs $READTHEDOCS_OUTPUT/html diff --git a/build_backend/dp_backend.py b/build_backend/dp_backend.py index 1542180..fa21935 100644 --- a/build_backend/dp_backend.py +++ b/build_backend/dp_backend.py @@ -31,7 +31,10 @@ def __dir__() -> list[str]: def cibuildwheel_dependencies() -> list[str]: - if os.environ.get("CIBUILDWHEEL", "0") == "1": + if ( + os.environ.get("CIBUILDWHEEL", "0") == "1" + or os.environ.get("READTHEDOCS", "0") == "True" + ): return [ "deepmd-kit[torch]>=3.0.0b2", ] diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..d4bb2cb --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = . +BUILDDIR = _build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..8678512 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,126 @@ +# SPDX-License-Identifier: LGPL-3.0-or-later +"""Configuration file for the Sphinx documentation builder.""" +# +# This file only contains a selection of the most common options. For a full +# list see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Path setup -------------------------------------------------------------- + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# + +# import sys +# sys.path.insert(0, os.path.abspath('..')) +from datetime import datetime, timezone + +# -- Project information ----------------------------------------------------- + +project = "DeePMD-GNN" +copyright = f"2024-{datetime.now(tz=timezone.utc).year}, DeepModeling" # noqa: A001 +author = "Jinzhe Zeng" + + +# -- General configuration --------------------------------------------------- + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ + "sphinx.ext.autosummary", + "sphinx.ext.mathjax", + "sphinx.ext.viewcode", + "sphinx.ext.intersphinx", + # "sphinxarg.ext", + "myst_parser", + # "sphinx_favicon", + "deepmodeling_sphinx", + "dargs.sphinx", + # "sphinxcontrib.bibtex", + # "sphinx_design", + "autoapi.extension", +] + +# Add any paths that contain templates here, relative to this directory. +# templates_path = ['_templates'] + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path. +exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] + + +# -- Options for HTML output ------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = "sphinx_book_theme" +# html_logo = "_static/logo.svg" +html_static_path = ["_static"] +html_js_files: list[str] = [] +html_css_files = ["css/custom.css"] +html_extra_path = ["report.html", "fire.png", "bundle.js", "bundle.css"] + +html_theme_options = { + "github_url": "https://github.com/deepmodeling/deepmd-gnn", + "gitlab_url": "https://gitlab.com/RutgersLBSR/deepmd-gnn", + "logo": { + "text": "DeePMD-GNN", + "alt_text": "DeePMD-GNN", + }, +} + +html_context = { + "github_user": "deepmodeling", + "github_repo": "deepmd-gnn", + "github_version": "master", + "doc_path": "docs", +} + +myst_heading_anchors = 3 + +# favicons = [ +# { +# "rel": "icon", +# "static-file": "logo.svg", +# "type": "image/svg+xml", +# }, +# ] + +enable_deepmodeling = False + +myst_enable_extensions = [ + "dollarmath", + "colon_fence", + "attrs_inline", +] +mathjax_path = ( + "https://cdnjs.cloudflare.com/ajax/libs/mathjax/3.2.2/es5/tex-mml-chtml.min.js" +) +mathjax_options = { + "integrity": "sha512-6FaAxxHuKuzaGHWnV00ftWqP3luSBRSopnNAA2RvQH1fOfnF/A1wOfiUWF7cLIOFcfb1dEhXwo5VG3DAisocRw==", + "crossorigin": "anonymous", +} +mathjax3_config = { + "loader": {"load": ["[tex]/mhchem"]}, + "tex": {"packages": {"[+]": ["mhchem"]}}, +} + +execution_mode = "off" +numpydoc_show_class_members = False + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +# html_static_path = ['_static'] + +intersphinx_mapping = { + "numpy": ("https://docs.scipy.org/doc/numpy/", None), + "python": ("https://docs.python.org/", None), + "deepmd": ("https://docs.deepmodeling.com/projects/deepmd/", None), + "torch": ("https://pytorch.org/docs/stable/", None), +} +autoapi_dirs = ["../deepmd_gnn"] diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..21ddec1 --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,18 @@ +.. include:: ../README.md + :parser: myst_parser.sphinx_ + +Table of contents +================= +.. toctree:: + :maxdepth: 2 + + Overview + parameters + Python API + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/docs/parameters.rst b/docs/parameters.rst new file mode 100644 index 0000000..84afb72 --- /dev/null +++ b/docs/parameters.rst @@ -0,0 +1,16 @@ +Parameters +========== + +MACE +---- + +.. dargs:: + :module: deepmd_gnn.argcheck + :func: mace_model_args + +NequIP +------ + +.. dargs:: + :module: deepmd_gnn.argcheck + :func: nequip_model_args diff --git a/pyproject.toml b/pyproject.toml index f0985a2..0af223f 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -51,6 +51,14 @@ test = [ 'pytest-cov', "dargs>=0.4.8", ] +docs = [ + "sphinx", + "sphinx-autoapi", + "myst-parser", + "deepmodeling-sphinx>=0.3.0", + "sphinx-book-theme", + "dargs", +] [tool.scikit-build] wheel.py-api = "py2.py3" @@ -96,6 +104,10 @@ convention = "numpy" "D101", "D102", ] +"docs/conf.py" = [ + "ERA001", + "INP001", +] [tool.coverage.report] include = ["deepmd_gnn/*"]