diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 0000000000..a7fb247281 --- /dev/null +++ b/.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 \ No newline at end of file diff --git a/cmake/FindSphinx.cmake b/cmake/FindSphinx.cmake index 30edee6de8..373d08ae3f 100644 --- a/cmake/FindSphinx.cmake +++ b/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 diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt index 0df64241d2..c9140332b3 100644 --- a/doc/CMakeLists.txt +++ b/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) diff --git a/doc/Doxyfile.in b/doc/Doxyfile.in index 8b1b64cfec..6f20062c6f 100644 --- a/doc/Doxyfile.in +++ b/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 diff --git a/doc/requirements.txt b/doc/requirements.txt new file mode 100644 index 0000000000..8eded424b7 --- /dev/null +++ b/doc/requirements.txt @@ -0,0 +1,4 @@ +breathe +exhale +sphinx +sphinx-rtd-theme diff --git a/doc/source/conf.in b/doc/source/conf.in index d8a545cf09..c35b3c5164 100644 --- a/doc/source/conf.in +++ b/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'] diff --git a/scripts/configure_for_rtd.sh b/scripts/configure_for_rtd.sh new file mode 100644 index 0000000000..25d09d0670 --- /dev/null +++ b/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 .. \ No newline at end of file