From f7ddf51772a7519c0cef2a785f458d1302ded577 Mon Sep 17 00:00:00 2001 From: Rohit Goswami Date: Mon, 2 Feb 2026 07:34:11 +0100 Subject: [PATCH] feat(docs): add complete C++ API reference --- .github/workflows/docs.yml | 6 +++- .gitignore | 3 ++ docs/Doxyfile.metatomic | 63 ++++++++++++++++++++++++++++++++++++++ docs/doxyrest-config.lua | 12 ++++++++ docs/src/conf.py | 5 +++ docs/src/index.rst | 2 ++ scripts/mkdoc.nu | 54 ++++++++++++++++++++++++++++++++ 7 files changed, 144 insertions(+), 1 deletion(-) create mode 100644 docs/Doxyfile.metatomic create mode 100644 docs/doxyrest-config.lua create mode 100644 scripts/mkdoc.nu diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 9c17b46c..4433b98c 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -31,12 +31,16 @@ jobs: run: | python -m pip install tox sudo apt install doxygen + wget -qO- https://apt.fury.io/nushell/gpg.key | sudo gpg --dearmor -o /etc/apt/keyrings/fury-nushell.gpg + echo "deb [signed-by=/etc/apt/keyrings/fury-nushell.gpg] https://apt.fury.io/nushell/ /" | sudo tee /etc/apt/sources.list.d/fury-nushell.list + sudo apt update + sudo apt install nushell liblua5.2-0 - name: build documentation env: # Use the CPU only version of torch when building/running the code PIP_EXTRA_INDEX_URL: https://download.pytorch.org/whl/cpu - run: tox -e docs + run: nu scripts/mkdoc.nu - name: store documentation as github artifact to be downloaded by users uses: actions/upload-artifact@v6 diff --git a/.gitignore b/.gitignore index ab865aa2..6cdb9733 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,4 @@ +.tmp # Python stuff __pycache__ *.egg-info/ @@ -7,3 +8,5 @@ build/ htmlcov/ .coverage* coverage.xml +/docs/src/api/ +/docs/subprojects/ diff --git a/docs/Doxyfile.metatomic b/docs/Doxyfile.metatomic new file mode 100644 index 00000000..a04cddf5 --- /dev/null +++ b/docs/Doxyfile.metatomic @@ -0,0 +1,63 @@ +# Customized Options +# Make changes here to prevent things from being overwritten when the main file +# is updated + +# Defaults +@INCLUDE = "./Doxyfile" + +# XML +GENERATE_XML = YES +XML_PROGRAMLISTING = NO +# Sphinx uses lowercase references so.. +CASE_SENSE_NAMES = NO +# Prevents links to template arguments +HIDE_UNDOC_RELATIONS = YES + +# HTML +GENERATE_HTML = NO +USE_MATHJAX = NO + +# LaTeX +GENERATE_LATEX = NO + +# Project Settings +PROJECT_NAME = "metatomic" + +# Doxygen Settings +RECURSIVE = YES +INPUT = ../metatomic-torch/include/metatomic \ + ../metatomic-torch/include/metatomic/torch +OUTPUT_DIRECTORY = build/doxygen +CREATE_SUBDIRS = YES + +# Language additions +OPTIMIZE_OUTPUT_FOR_C = NO +BUILTIN_STL_SUPPORT = NO + +# Style +JAVADOC_BANNER = YES +JAVADOC_AUTOBRIEF = NO +INHERIT_DOCS = YES +INLINE_SOURCES = YES +SOURCE_BROWSER = YES +DISABLE_INDEX = NO +GENERATE_TREEVIEW = NO +HAVE_DOT = YES +DOT_IMAGE_FORMAT = YES +HTML_DYNAMIC_SECTIONS = YES +INTERACTIVE_SVG = YES +# # We link to standard definitions +# TAGFILES += "./tags/cppreference-doxygen-web.tag.xml=http://en.cppreference.com/w/" + +# Extract everything +EXTRACT_ALL = NO +EXTRACT_PRIVATE = YES +EXTRACT_PRIV_VIRTUAL = YES +EXTRACT_PACKAGE = YES +EXTRACT_STATIC = YES +MACRO_EXPANSION = YES +ENABLE_PREPROCESSING = YES + +# Local Variables: +# mode: conf +# End: diff --git a/docs/doxyrest-config.lua b/docs/doxyrest-config.lua new file mode 100644 index 00000000..91a2c14d --- /dev/null +++ b/docs/doxyrest-config.lua @@ -0,0 +1,12 @@ +INPUT_FILE = "build/doxygen/xml/index.xml" +OUTPUT_FILE = "src/api/index.rst" +INDEX_TITLE = "C++ API Reference" + +FRAME_DIR_LIST = { + "subprojects/doxyrest/frame/common", + "subprojects/doxyrest/frame/cfamily" +} + +LANGUAGE = "cpp" +ESCAPE_ASTERISKS = true +ESCAPE_TRAILING_UNDERSCORES = true diff --git a/docs/src/conf.py b/docs/src/conf.py index 74ff15ea..1f6cddc1 100644 --- a/docs/src/conf.py +++ b/docs/src/conf.py @@ -17,6 +17,8 @@ ROOT = os.path.abspath(os.path.join(os.path.dirname(__file__), "..", "..")) sys.path.append(os.path.join(ROOT, "docs", "extensions")) +# For doxyrest +sys.path.insert(0, os.path.join(ROOT, "docs", "subprojects", "doxyrest", "sphinx")) # We use a second (pseudo) sphinx project located in `docs/generate_examples` to run the # examples and generate the actual output for our sphinx-gallery. This is necessary @@ -135,6 +137,9 @@ def setup(app): "myst_parser", "sphinx_design", "chemiscope.sphinx", + # c++ helpers + "doxyrest", + "cpplexer", # local extensions "versions_list", ] diff --git a/docs/src/index.rst b/docs/src/index.rst index d41b2501..a30728eb 100644 --- a/docs/src/index.rst +++ b/docs/src/index.rst @@ -95,4 +95,6 @@ existing trained models, look into the metatrain_ project instead. outputs/index engines/index examples/index + api/global + api/index cite diff --git a/scripts/mkdoc.nu b/scripts/mkdoc.nu new file mode 100644 index 00000000..5daeaa93 --- /dev/null +++ b/scripts/mkdoc.nu @@ -0,0 +1,54 @@ +#!/usr/bin/env nu + +def main [] { + let root = ($env.PWD) + let deps_dir = ($root | path join "docs/subprojects") + let doxyrest_src = ($deps_dir | path join "doxyrest") + let install_dir = ($deps_dir | path join "install") + let has_doxyrest = (which doxyrest | is-not-empty) + + # Setup Directory Structure + if not ($deps_dir | path exists) { + mkdir $deps_dir + } + + # Grab Doxyrest if missing + if not $has_doxyrest and not ($install_dir | path exists) { + print "Downloading Doxyrest binary release..." + let version = "2.1.3" + let target = "linux-amd64" + let archive = $"doxyrest-($version)-($target).tar.xz" + let url = $"https://github.com/vovkos/doxyrest/releases/download/doxyrest-($version)/($archive)" + + cd $deps_dir + http get $url | save $archive + tar -xJf $archive + + if ($install_dir | path exists) { rm -rf $install_dir } + mv $"doxyrest-($version)-($target)" $install_dir + + rm $archive + cd $root + } + + # Still needed for the frames.. + if not ($doxyrest_src | path exists) { + print $"Cloning doxyrest into ($doxyrest_src)..." + git clone --depth 1 --single-branch https://github.com/vovkos/doxyrest $doxyrest_src + } + + # Run the Pipeline + print "Generating XML with Doxygen..." + cd docs + mkdir build/doxygen/xml + doxygen Doxyfile.metatomic + + print "Generating RST with local Doxyrest..." + # Add local bin to path for this execution + with-env { PATH: ($env.PATH | prepend ($install_dir | path join "bin")) } { + doxyrest -c doxyrest-config.lua + } + + print "Building HTML with Sphinx (tox)..." + tox -e docs +}