From b0eedd9ed6ad3885d9fd3953cf891de0c6775886 Mon Sep 17 00:00:00 2001 From: Daniel Weindl Date: Fri, 1 Dec 2023 11:42:32 +0100 Subject: [PATCH] Update documentation stack / tox.ini for building documentation (#2213) * Update exhale, sphinx, ... to fix some incompatibilities * Set up tox.ini for building documentation --- .github/workflows/test_doc.yml | 4 ++-- documentation/README.md | 8 +------- documentation/conf.py | 3 ++- documentation/rtd_requirements.txt | 14 +++++++------- documentation/rtd_requirements2.txt | 2 +- scripts/run-sphinx-hasenv.sh | 17 ----------------- scripts/run-sphinx.sh | 16 ---------------- tox.ini | 24 ++++++++++++++++++++++++ 8 files changed, 37 insertions(+), 51 deletions(-) delete mode 100755 scripts/run-sphinx-hasenv.sh delete mode 100755 scripts/run-sphinx.sh create mode 100644 tox.ini diff --git a/.github/workflows/test_doc.yml b/.github/workflows/test_doc.yml index 07e0afdcc8..ca4766c5eb 100644 --- a/.github/workflows/test_doc.yml +++ b/.github/workflows/test_doc.yml @@ -67,10 +67,10 @@ jobs: sudo apt-get update \ && sudo apt-get install -y \ pandoc \ - python3-venv + && pip install tox - name: Set up SWIG uses: ./.github/actions/setup-swig - name: Run sphinx - run: scripts/run-sphinx.sh + run: tox -e doc diff --git a/documentation/README.md b/documentation/README.md index af9f33320e..eece1de90e 100644 --- a/documentation/README.md +++ b/documentation/README.md @@ -12,7 +12,7 @@ The legacy GitHub Pages URL https://amici-dev.github.io/AMICI/ is set up as a redirect to RTD. The main configuration file is `documentation/conf.py` and the documentation -is generated using `scripts/run-sphinx.sh`. The documentation is written to +is generated using `tox -e doc`. The documentation is written to `documentation/_build/`. The documentation comprises: @@ -50,12 +50,6 @@ Matlab documentation is processed by [mtoc++](https://www.morepas.org/software/mtocpp/docs/tools.html). This is configured in `matlab/mtoc/config`. -#### Python documentation - -Python documentation is processed by doxygen and doxypypy using the script and -filters in `scripts/`. - - ## Writing documentation ### Out-of-source documentation diff --git a/documentation/conf.py b/documentation/conf.py index ba88b25a8d..0297c08ef8 100644 --- a/documentation/conf.py +++ b/documentation/conf.py @@ -567,7 +567,8 @@ def process_signature( return # only apply in the amici.amici module - if name.split(".")[1] != "amici": + split_name = name.split(".") + if len(split_name) < 2 or split_name[1] != "amici": return signature = fix_typehints(signature) diff --git a/documentation/rtd_requirements.txt b/documentation/rtd_requirements.txt index 64bc03e519..ae49f9dfbb 100644 --- a/documentation/rtd_requirements.txt +++ b/documentation/rtd_requirements.txt @@ -1,7 +1,7 @@ # NOTE: relative paths are expected to be relative to the repository root -sphinx<7 +sphinx mock>=5.0.2 -setuptools==67.7.2 +setuptools>=67.7.2 pysb>=1.11.0 matplotlib==3.7.1 nbsphinx==0.9.1 @@ -9,15 +9,15 @@ nbformat==5.8.0 recommonmark>=0.7.1 sphinx_rtd_theme>=1.2.0 petab[vis]>=0.2.0 -sphinx-autodoc-typehints==1.23.0 +sphinx-autodoc-typehints git+https://github.com/readthedocs/sphinx-hoverxref@main -ipython==8.13.2 -breathe==4.35.0 +ipython>=8.13.2 +breathe>=4.35.0 #exhale>=0.3.5 -e git+https://github.com/mithro/sphinx-contrib-mithro#egg=sphinx-contrib-exhale-multiproject&subdirectory=sphinx-contrib-exhale-multiproject -sphinxcontrib-matlabdomain<0.19.0 +sphinxcontrib-matlabdomain>=0.20.0 sphinxcontrib-napoleon>=0.7 -pygments==2.15.1 +pygments>=2.15.1 Jinja2==3.1.2 git+https://github.com/readthedocs/readthedocs-sphinx-ext ipykernel diff --git a/documentation/rtd_requirements2.txt b/documentation/rtd_requirements2.txt index 5a39f8e683..2c307f0ea4 100644 --- a/documentation/rtd_requirements2.txt +++ b/documentation/rtd_requirements2.txt @@ -1 +1 @@ -exhale>=0.3.6 +-e git+https://github.com/svenevs/exhale.git@a1a8551321e246e3ab81f5456e04a8159804595b#egg=exhale diff --git a/scripts/run-sphinx-hasenv.sh b/scripts/run-sphinx-hasenv.sh deleted file mode 100755 index e401737022..0000000000 --- a/scripts/run-sphinx-hasenv.sh +++ /dev/null @@ -1,17 +0,0 @@ -#!/bin/bash -# Build the sphinx documentation in an environment prepared -# as in run-sphinx.sh already - -SCRIPT_PATH=$(dirname $BASH_SOURCE) -AMICI_PATH=$(cd $SCRIPT_PATH/.. && pwd) - -source ${AMICI_PATH}/doc-venv/bin/activate - -cd ${AMICI_PATH}/documentation - -rm -rf ${AMICI_PATH}/documentation/generated - -sphinx-build -T -E -W --keep-going -b readthedocs -d _build/doctrees-readthedocs -D language=en . _build/html - -ret=$? -if [[ $ret != 0 ]]; then exit $ret; fi diff --git a/scripts/run-sphinx.sh b/scripts/run-sphinx.sh deleted file mode 100755 index e7b1ce0861..0000000000 --- a/scripts/run-sphinx.sh +++ /dev/null @@ -1,16 +0,0 @@ -#!/bin/bash -# generate code documentation via sphinx for upload to rtd - -SCRIPT_PATH=$(dirname $BASH_SOURCE) -AMICI_PATH=$(cd $SCRIPT_PATH/.. && pwd) - -python3 -m venv ${AMICI_PATH}/doc-venv --clear -source ${AMICI_PATH}/doc-venv/bin/activate -python -m pip install --upgrade --no-cache-dir pip setuptools wheel -(cd ${AMICI_PATH}/ && python -m pip install --exists-action=w --no-cache-dir -r documentation/rtd_requirements.txt) -(cd ${AMICI_PATH}/ && python -m pip install --exists-action=w --no-cache-dir -r documentation/rtd_requirements2.txt) - -${AMICI_PATH}/scripts/run-sphinx-hasenv.sh - -ret=$? -if [[ $ret != 0 ]]; then exit $ret; fi diff --git a/tox.ini b/tox.ini new file mode 100644 index 0000000000..a61ee8a6e2 --- /dev/null +++ b/tox.ini @@ -0,0 +1,24 @@ +[tox] +env_list = + py311 +minversion = 4.11.3 +envlist = + doc + +[testenv] +passenv = AMICI_PARALLEL_COMPILE,CC,CXX + +[testenv:doc] +description = + Build documentation +deps = + -r documentation/rtd_requirements.txt + -r documentation/rtd_requirements2.txt +# don't install the package, this is already handled by `deps` above +skip_install = true +change_dir = documentation/ +allowlist_externals = + rm +commands = + rm -rf amici_models/ _doxyoutput_amici_cpp/ _exhale_cpp_api/ _exhale_matlab_api/ + sphinx-build -T -E -W --keep-going -b readthedocs -d _build/doctrees-readthedocs -D language=en . _build/html