Sphinx documentation update

.readthedocs.yaml

@@ -0,0 +1,64 @@
+#  This file is part of t8code.
+#  t8code is a C library to manage a collection (a forest) of multiple
+#  connected adaptive space-trees of general element types in parallel.
+#
+#  Copyright (C) 2025 the developers
+#
+#  t8code is free software; you can redistribute it and/or modify
+#  it under the terms of the GNU General Public License as published by
+#  the Free Software Foundation; either version 2 of the License, or
+#  (at your option) any later version.
+#
+#  t8code is distributed in the hope that it will be useful,
+#  but WITHOUT ANY WARRANTY; without even the implied warranty of
+#  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+#  GNU General Public License for more details.
+#
+#  You should have received a copy of the GNU General Public License
+#  along with t8code; if not, write to the Free Software Foundation, Inc.,
+#  51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
+
+# Read the Docs configuration file for Sphinx projects
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the OS, Python version and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.12"
+  apt_packages:
+    - cmake
+    - ninja-build
+  jobs:
+    post_checkout:
+      - git fetch --unshallow --tags || true  # Fetch all tags to ensure we can build documentation for any version
+    post_install:
+      - bash ./scripts/configure_for_rtd.sh
+
+    # You can also specify other tool versions:
+    # nodejs: "20"
+    # rust: "1.70"
+    # golang: "1.20"
+
+# Build documentation in the "docs/" directory with Sphinx
+sphinx:
+  configuration: doc/source/conf.py
+  # You can configure Sphinx to use a different builder, for instance use the dirhtml builder for simpler URLs
+  # builder: "dirhtml"
+  # Fail on all warnings to avoid broken references
+  # fail_on_warning: true
+
+# Optionally build your docs in additional formats such as PDF and ePub
+# formats:
+#   - pdf
+#   - epub
+
+# Optional but recommended, declare the Python requirements required
+# to build your documentation
+# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
+python:
+  install:
+    - requirements: doc/requirements.txt

cmake/FindSphinx.cmake

@@ -18,12 +18,25 @@
 #  along with t8code; if not, write to the Free Software Foundation, Inc.,
 #  51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
 
+include(FindPackageHandleStandardArgs)
+
+find_package(PythonInterp)
+if(PYTHONINTERP_FOUND)
+    get_filename_component(_PYTHON_DIR "${PYTHON_EXECUTABLE}" DIRECTORY)
+    set(
+        _PYTHON_PATHS
+        "${_PYTHON_DIR}"
+        "{_PYTHON_DIR}/bin"
+        "{_PYTHON_DIR}/Scripts"
+    )
+endif()
+
 #Look for an executable called sphinx-build
 find_program(SPHINX_EXECUTABLE
-             NAMES sphinx-build
+             NAMES sphinx-build sphinx-build.exe sphinx-build.py
+             HINTS ${_PYTHON_PATHS}
              DOC "Path to sphinx-build executable")
 
-include(FindPackageHandleStandardArgs)
 
 #Handle standard arguments to find_package like REQUIRED and QUIET
 find_package_handle_standard_args(Sphinx

doc/CMakeLists.txt

@@ -39,8 +39,8 @@ if(T8CODE_BUILD_DOCUMENTATION)
 
         add_custom_command( OUTPUT ${DOXYGEN_INDEX_FILE}
                             DEPENDS ${T8_PUBLIC_HEADERS}
-                            COMMAND ${DOXYGEN_EXECUTABLE} ${DOXYFILE_OUT} 
-                            MAIN_DEPENDENCY ${DOXYFILE_OUT} ${DOXYFILE_IN} 
+                            COMMAND ${DOXYGEN_EXECUTABLE} ${DOXYFILE_OUT}
+                            MAIN_DEPENDENCY ${DOXYFILE_OUT} ${DOXYFILE_IN}
                             COMMENT "Generating documentation"
                             VERBATIM)
 
@@ -53,9 +53,9 @@ endif(T8CODE_BUILD_DOCUMENTATION)
 
 if (T8CODE_BUILD_DOCUMENTATION_SPHINX)
     find_package(Sphinx REQUIRED)
-    
+
     configure_file(${DOXYFILE_IN} ${DOXYFILE_OUT} @ONLY)
-    
+
     if (SPHINX_FOUND)
         set(SPHINX_SOURCE ${PROJECT_SOURCE_DIR}/doc/source)
         set(SPHINX_BUILD ${PROJECT_BINARY_DIR}/doc/sphinx)
@@ -85,7 +85,7 @@ if (T8CODE_BUILD_DOCUMENTATION_SPHINX)
                             MAIN_DEPENDENCY ${SPHINX_SOURCE}/conf.py
                             COMMENT "Generating documentation with Sphinx")
 
-        
+
         # Nice named target so we can run the job easily
         add_custom_target(Sphinx ALL DEPENDS ${SPHINX_INDEX_FILE})
     else (SPHINX_FOUND)

doc/Doxyfile.in

@@ -2044,7 +2044,7 @@ MAN_LINKS              = NO
 # captures the structure of the code including all documentation.
 # The default value is: NO.
 
-GENERATE_XML           = NO
+GENERATE_XML           = YES
 
 # The XML_OUTPUT tag is used to specify where the XML pages will be put. If a
 # relative path is entered the value of OUTPUT_DIRECTORY will be put in front of

doc/requirements.txt

@@ -0,0 +1,4 @@
+breathe
+exhale
+sphinx
+sphinx-rtd-theme

doc/source/conf.in

@@ -6,6 +6,8 @@
 # -- Project information -----------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
+import subprocess, os
+
 project = 't8code'
 copyright = '2024, Johannes Holke, David Knapp, Sandro Elsweijer, Ioannis Lilikakis, Lukas Dreyer, Jakob Fußbroich, Carsten Burstedde, Chiara Hergl, Johannes Markert, Niklas Boeing, Florian Becker, Prasanna Ponnusamy'
 author = 'Johannes Holke, David Knapp, Sandro Elsweijer, Ioannis Lilikakis, Lukas Dreyer, Jakob Fußbroich, Carsten Burstedde, Chiara Hergl, Johannes Markert, Niklas Boeing, Florian Becker, Prasanna Ponnusamy'
@@ -14,7 +16,7 @@ version = '@VERSION@'
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
-extensions = [ "breathe", "exhale", "sphinx.ext.mathjax", "sphinx.ext.graphviz" ]
+extensions = [ 'breathe', 'exhale', 'sphinx.ext.mathjax', 'sphinx.ext.graphviz' ]
 
 templates_path = ['_templates']
 exclude_patterns = []
@@ -23,11 +25,39 @@ exclude_patterns = []
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
+# Breathe Configuration
+breathe_projects = {}
+
+def configureDoxyfile(input_dir, output_dir):
+    with open('../Doxyfile.in', 'r') as file :
+        filedata = file.read()
+
+    filedata = filedata.replace('@DOXYGEN_INPUT_DIR@', input_dir)
+    filedata = filedata.replace('@DOXYGEN_OUTPUT_DIR@', output_dir)
+
+    with open('../Doxyfile', 'w') as file:
+        file.write(filedata)
+
+# Check if we're running on Read the Docs' servers
+read_the_docs_build = os.environ.get('READTHEDOCS', None) == 'True'
+
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+breathe_projects = {}
+
+if read_the_docs_build:
+    input_dir = '../../src'
+    output_dir = 'build'
+    configureDoxyfile(input_dir, output_dir)
+    subprocess.call('doxygen', shell=True)
+    breathe_projects["T8code"] = output_dir + '/xml'
+
 html_theme = 'sphinx_rtd_theme'
 html_static_path = ['_static']
 html_logo = '../../t8code_logo.png'
 
-# Breathe Configuration
 breathe_default_project = "T8code"
 breathe_implementation_filename_extensions = ['.c', '.cpp']
 

scripts/configure_for_rtd.sh

@@ -0,0 +1,19 @@
+#!/bin/bash
+
+git submodule init
+git submodule update
+
+# Create the build directory
+mkdir build
+
+# Navigate into the build directory
+cd build
+
+# Run cmake with the specified options
+cmake .. -DT8CODE_BUILD_DOCUMENTATION=ON -DT8CODE_BUILD_DOCUMENTATION_SPHINX=ON -DT8CODE_ENABLE_MPI=OFF
+
+# Build the project with make
+make -j V=0
+
+# Return to the parent directory
+cd ..