Merge pull request #36 from EXP-code/Doxygen

Generate the XML files needed by Sphinx+Breathe from Doxgyen at build time

Author: The9Cat

.github/workflows/build_docs.yml

@@ -0,0 +1,43 @@
+name: Build and Deploy Sphinx Docs
+
+on:
+  push:
+    branches:
+      - main                    # Trigger on pushes to the main branch
+      - Doxygen                 # Trigger on pushes to the devel branch
+
+jobs:
+  build:
+    runs-on: ubuntu-24.04  # Specify the operating system
+
+    steps:
+      - uses: actions/checkout@v4  # Checkout the repository
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.x'  # Specify your Python version
+      - name: Install dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y build-essential libeigen3-dev libfftw3-dev libhdf5-dev libopenmpi-dev libomp-dev python3-numpy python3-venv python3-ipython ipython3 doxygen graphviz cmake make pandoc
+          python3 -m venv .venv # Create a virtual environment
+          source .venv/bin/activate # Activate the environment
+          pip install sphinx sphinx-rtd-theme  # Install Sphinx and theme
+          pip install -r requirements.txt  # Install any additional dependencies (optional)
+      - name: Build Sphinx documentation
+        run: |
+          source .venv/bin/activate # Activate the environment
+          make html  # Build the HTML documentation
+      - name: Upload built documentation (optional)
+        uses: actions/upload-artifact@v4
+        with:
+          name: html-docs
+          path: _build/html  # Path to your built documentation
+      - name: Deploy to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v3
+        if: ${{ github.event_name == 'push' }}
+        with:
+          publish_branch: gh-pages
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: _build/html
+          force_orphan: true

.readthedocs.yaml

@@ -6,15 +6,23 @@ version: 2
 
 # Set the OS, Python version and other tools you might need
 build:
-  os: ubuntu-22.04
+  os: ubuntu-24.04
   tools:
-    python: "3.11"
+    python: "3.12"
     # You can also specify other tool versions:
     # nodejs: "20"
     # rust: "1.70"
     # golang: "1.20"
   apt_packages:
     - graphviz
+    - cmake
+    - make
+    - libeigen3-dev
+    - libfftw3-dev
+    - libhdf5-dev
+    - libopenmpi-dev
+    - openmpi-bin
+    - openmpi-common
 
 # Build documentation in the "docs/" directory with Sphinx
 sphinx:

conf.py

@@ -3,13 +3,78 @@
 # For the full list of built-in configuration values, see the documentation:
 # https://www.sphinx-doc.org/en/master/usage/configuration.html
 
-# -- Project information -----------------------------------------------------
-# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+import os, sys
+import subprocess
 
+on_rtd = os.environ.get("READTHEDOCS") == "True"
+
+
+# -- Generate doxygen xml prior to build --------------------------------------
+
+# Define the repository URL and target directory
+#
+repo_url  = "https://github.com/EXP-code/EXP.git"
+clone_dir = "exp_repo"
+branch    = "SLboundaries"
+doxyfile  = "exp.cfg.breathe"
+doxy_dir  = "doc"
+
+# Cache the current working directory
+#
+build_dir = os.getcwd()
+
+# Clone the EXP repository if it doesn't exist
+#
+if not os.path.exists(clone_dir):
+    subprocess.run(["git", "clone", repo_url, clone_dir], check=True)
+
+# Move to source and get the desired branch
+#
+os.chdir(clone_dir)
+subprocess.run(["git", "checkout", branch])
+subprocess.run(["cp", "CMakeLists.txt", "CMakeLists.txt.orig"])
+command = ["sed", "-i", "-e", 's/VERSION 3.25/VERSION 3.22/g', "CMakeLists.txt"] 
+result = subprocess.run(command, capture_output=True, text=True, check=True)
+
+# Initialize submodules
+#
+os.chdir(doxy_dir)
+os.system("git submodule update --init --recursive")
+
+# Ensure Doxygen is installed and its executable is in your PATH
+#
+subprocess.run(["doxygen", doxyfile], check=True)
+
+if not on_rtd:
+    # Build pyEXP to populate Python API documenation
+    #
+    os.chdir('..')
+
+    # Make build directory and begin
+    #
+    if not os.path.exists('build'):
+        subprocess.run(["mkdir", "build"], check=True)
+    os.chdir('build')
+    subprocess.run(['cmake', '-DCMAKE_BUILD_TYPE=Release -DENABLE_USER=NO -DENABLE_NBODY=NO -DEigen3_DIR=$EIGEN_BASE/share/eigen3/cmake -Wno-dev', '..'])
+    subprocess.run(['make', '-j8'])
+
+    # Return to top level
+    #
+    os.chdir(build_dir)
+
+    # Add 'my_module_path' to the beginning of sys.path
+    #
+    my_module_path = os.path.join(build_dir, 'exp_repo/build/pyEXP')
+    sys.path.insert(0, my_module_path)
+
+# Begin Sphinx configuration
+
+# -- project information -----------------------------------------------------
+#
 project = 'EXP'
 copyright = '2023-2025, EXP-code collaboration'
 author = 'EXP-code collaboration'
-release = '0.16'
+release = '0.17'
 version = '7.x'
 
 # -- General configuration ---------------------------------------------------
@@ -36,7 +101,7 @@
 templates_path = ['_templates']
 exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', 'README.rst']
 
-breathe_projects = {"EXP": "doxyxml/"}
+breathe_projects = {"EXP": "exp_repo/doc/xml/"}
 breathe_default_project = "EXP"
 
 # -- Options for HTML output -------------------------------------------------
@@ -46,14 +111,16 @@
 html_logo = 'exp_logo_white.png'
 html_static_path = ['_static']
 
+# -- A readthedocs conditional  ----------------------------------------------
+if on_rtd:
+    tags.add('rtd')
+
 # -- Turn on figure numering -------------------------------------------------
 numfig = True
 
 # -- Extension configuration -------------------------------------------------
 nbsphinx_execute = 'never'
 
 # -- Grab files from pyEXP-examples -----------------------------------------
-import os
-
 os.system("cd intro/Tutorials; rm *ipynb*; wget -L https://raw.githubusercontent.com/EXP-code/pyEXP-examples/refs/heads/main/Tutorials/Introduction/Part1-Coefficients.ipynb; wget -L https://raw.githubusercontent.com/EXP-code/pyEXP-examples/refs/heads/main/Tutorials/Introduction/Part2-Analysis.ipynb")