doc: intersphinx, tox env

* Simplify linking to the PEtab specs
* Add tox env for building the documentation

Author: dweindl

doc/conf.py

@@ -47,6 +47,7 @@
 ]
 
 intersphinx_mapping = {
+    "petab": ("https://petab.readthedocs.io/en/latest/", None),
     "pandas": ("https://pandas.pydata.org/docs/", None),
     "numpy": ("https://numpy.org/devdocs/", None),
     "sympy": ("https://docs.sympy.org/latest/", None),
@@ -62,7 +63,7 @@
 exclude_patterns = [
     "build/doctrees",
     "build/html",
-    "**.ipynb_checkpoints",
+    "build/jupyter_execute/**" "**.ipynb_checkpoints",
     "logo/LICENSE.md",
 ]
 

petab/v1/problem.py

@@ -41,7 +41,9 @@
 
 class Problem:
     """
-    PEtab parameter estimation problem as defined by
+    PEtab parameter estimation problem.
+
+    A PEtab problem as defined by:
 
     - model
     - condition table
@@ -50,7 +52,9 @@ class Problem:
     - observables table
     - mapping table
 
-    Optionally it may contain visualization tables.
+    Optionally, it may contain visualization tables.
+
+    See also :doc:`petab:v1/documentation_data_format`.
 
     Parameters:
         condition_df: PEtab condition table

petab/v2/problem.py

@@ -39,7 +39,9 @@
 
 class Problem:
     """
-    PEtab parameter estimation problem as defined by
+    PEtab parameter estimation problem
+
+    A PEtab parameter estimation problem as defined by
 
     - model
     - condition table
@@ -49,7 +51,9 @@ class Problem:
     - observables table
     - mapping table
 
-    Optionally it may contain visualization tables.
+    Optionally, it may contain visualization tables.
+
+    See also :doc:`petab:v2/documentation_data_format`.
 
     Parameters:
         condition_df: PEtab condition table

tox.ini

@@ -1,5 +1,5 @@
 [tox]
-envlist = quality,unit
+envlist = quality,unit,doc
 isolated_build = True
 
 [testenv]
@@ -23,3 +23,16 @@ commands =
     tests
 description =
   Basic tests
+
+[testenv:doc]
+description = Build the documentation
+extras = doc,vis
+deps=
+  # workaround for m2r2 issue with py3.13: No module named 'pkg_resources'
+  #  see also: https://github.com/CrossNox/m2r2/issues/72
+  setuptools
+allowlist_externals = rm
+commands =
+    rm -rf {tox_root}/doc/build
+    sphinx-build -W -b html . build/html
+changedir = {tox_root}/doc