Update documentation stack / tox.ini for building documentation (AMIC…

…I-dev#2213)

* Update exhale, sphinx, ... to fix some incompatibilities
* Set up tox.ini for building documentation

.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

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

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)

documentation/rtd_requirements.txt

@@ -1,23 +1,23 @@
 # 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
 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

documentation/rtd_requirements2.txt

@@ -1 +1 @@
-exhale>=0.3.6
+-e git+https://github.com/svenevs/exhale.git@a1a8551321e246e3ab81f5456e04a8159804595b#egg=exhale

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