From d6d74524ef51f73e5cde46ef79f6524f6b4c194e Mon Sep 17 00:00:00 2001
From: Daniel Weindl <daniel.weindl@uni-bonn.de>
Date: Wed, 12 Mar 2025 12:36:25 +0100
Subject: [PATCH] doc: intersphinx, tox env

* Simplify linking to the PEtab specs
* Add tox env for building the documentation
---
 doc/conf.py         |  2 ++
 petab/v1/problem.py |  8 ++++++--
 petab/v2/problem.py |  8 ++++++--
 tox.ini             | 15 ++++++++++++++-
 4 files changed, 28 insertions(+), 5 deletions(-)

diff --git a/doc/conf.py b/doc/conf.py
index 4dbd3009..56f137e6 100644
--- a/doc/conf.py
+++ b/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,6 +63,7 @@
 exclude_patterns = [
     "build/doctrees",
     "build/html",
+    "build/jupyter_execute",
     "**.ipynb_checkpoints",
     "logo/LICENSE.md",
 ]
diff --git a/petab/v1/problem.py b/petab/v1/problem.py
index 2405f5c0..4f7df659 100644
--- a/petab/v1/problem.py
+++ b/petab/v1/problem.py
@@ -42,7 +42,9 @@
 
 class Problem:
     """
-    PEtab parameter estimation problem as defined by
+    PEtab parameter estimation problem.
+
+    A PEtab problem as defined by:
 
     - model
     - condition table
@@ -51,7 +53,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
diff --git a/petab/v2/problem.py b/petab/v2/problem.py
index 86d82af4..d18b4b7c 100644
--- a/petab/v2/problem.py
+++ b/petab/v2/problem.py
@@ -40,7 +40,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
@@ -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:v2/documentation_data_format`.
 
     Parameters:
         condition_df: PEtab condition table
diff --git a/tox.ini b/tox.ini
index 7d0cdccc..3f3bbe46 100644
--- a/tox.ini
+++ b/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