feat(docs): add complete C++ API reference

Author: HaoZeke

.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

.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/

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:

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

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",
 ]

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

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
+}