Fix documentation after PEtab refactoring

.github/workflows/test_doc.yml

@@ -43,7 +43,7 @@ jobs:
 
     strategy:
       matrix:
-        python-version: [ "3.10" ]
+        python-version: [ "3.11" ]
 
     steps:
       - name: Set up Python ${{ matrix.python-version }}

.readthedocs.yml

@@ -24,4 +24,4 @@ build:
     - libatlas-base-dev
     - swig
   tools:
-    python: "3.9"
+    python: "3.11"

documentation/conf.py

@@ -10,6 +10,7 @@
 import re
 import subprocess
 import sys
+from enum import EnumType
 
 # need to import before setting typing.TYPE_CHECKING=True, fails otherwise
 import amici
@@ -254,6 +255,7 @@ def install_doxygen():
 autodoc_default_options = {
     "special-members": "__init__",
     "inherited-members": True,
+    "undoc-members": True,
 }
 
 # sphinx-autodoc-typehints
@@ -606,7 +608,7 @@ def process_missing_ref(app, env, node, contnode):
 
 
 def skip_member(app, what, name, obj, skip, options):
-    ignored = [
+    ignored_names = {
         "AbstractModel",
         "CVodeSolver",
         "IDASolver",
@@ -615,7 +617,6 @@ def skip_member(app, what, name, obj, skip, options):
         "ConditionContext",
         "checkSigmaPositivity",
         "createGroup",
-        "createGroup",
         "equals",
         "printErrMsgIdAndTxt",
         "wrapErrHandlerFn",
@@ -640,24 +641,45 @@ def skip_member(app, what, name, obj, skip, options):
         "stdVec2ndarray",
         "SwigPyIterator",
         "thisown",
-    ]
+    }
 
-    if name in ignored:
+    if name in ignored_names:
         return True
 
     if name.startswith("_") and name != "__init__":
         return True
 
+    obj_str = str(obj)
+
     # ignore various functions for std::vector<> types
-    if re.match(r"^<function [\w]+Vector\.", str(obj)):
+    if re.match(r"^<function [\w]+Vector\.", obj_str):
         return True
 
     # ignore various functions for smart pointer types
-    if re.match(r"^<function [\w]+Ptr\.", str(obj)):
+    if re.match(r"^<function [\w]+Ptr\.", obj_str):
         return True
 
     # ignore various functions for StringDoubleMap
-    if str(obj).startswith("<function StringDoubleMap"):
+    if obj_str.startswith("<function StringDoubleMap"):
+        return True
+
+    # Skip inherited members from builtins
+    #  (skips, for example, all the int/str-derived methods of enums
+    if (
+        objclass := getattr(obj, "__objclass__", None)
+    ) and objclass.__module__ == "builtins":
+        return True
+
+    # Avoid the following issue for all enum types:
+    # > python/sdist/amici/amici.py:docstring of amici.amici.FixedParameterContext.from_bytes:9:
+    #   WARNING: Inline interpreted text or phrase reference start-string without end-string.
+    if (
+        (qualname := getattr(obj, "__qualname__", ""))
+        and qualname == "int.to_bytes"
+    ) or (
+        isinstance(getattr(obj, "__self__", None), EnumType)
+        and name == "from_bytes"
+    ):
         return True
 
     return None

python/sdist/amici/parameter_mapping.py

@@ -1,3 +1,9 @@
+"""Parameter mapping between AMICI and PEtab.
+
+.. deprecated:: 0.21.0
+    Use :mod:`amici.petab.parameter_mapping` instead.
+"""
+
 # some extra imports for backward-compatibility
 import warnings
 
@@ -22,3 +28,18 @@
     "Importing amici.parameter_mapping is deprecated. Use `amici.petab.parameter_mapping` instead.",
     DeprecationWarning,
 )
+
+__all__ = [
+    "fill_in_parameters",
+    "fill_in_parameters_for_condition",
+    "ParameterMapping",
+    "ParameterMappingForCondition",
+    "SingleParameterMapping",
+    "SingleScaleMapping",
+    "amici_to_petab_scale",
+    "petab_to_amici_scale",
+    "scale_parameter",
+    "scale_parameters_dict",
+    "unscale_parameter",
+    "unscale_parameters_dict",
+]

python/sdist/amici/petab/__init__.py

@@ -3,3 +3,33 @@
 # ID of model parameter that is to be added to SBML model to indicate
 #  preequilibration
 PREEQ_INDICATOR_ID = "preequilibration_indicator"
+
+from .petab_import import import_petab_problem
+from .simulations import (
+    EDATAS,
+    FIM,
+    LLH,
+    RDATAS,
+    RES,
+    S2LLH,
+    SLLH,
+    SRES,
+    rdatas_to_measurement_df,
+    rdatas_to_simulation_df,
+    simulate_petab,
+)
+
+__all__ = [
+    "import_petab_problem",
+    "simulate_petab",
+    "rdatas_to_simulation_df",
+    "rdatas_to_measurement_df",
+    "LLH",
+    "SLLH",
+    "FIM",
+    "S2LLH",
+    "RES",
+    "SRES",
+    "RDATAS",
+    "EDATAS",
+]

python/sdist/amici/petab/petab_import.py

@@ -25,6 +25,9 @@
     # pysb not available
     import_model_pysb = None
 
+
+__all__ = ["import_petab_problem"]
+
 logger = get_logger(__name__, logging.WARNING)
 
 
@@ -37,19 +40,18 @@ def import_petab_problem(
     **kwargs,
 ) -> "amici.Model":
     """
-    Import model from petab problem.
+    Create an AMICI model for a PEtab problem.
 
     :param petab_problem:
         A petab problem containing all relevant information on the model.
 
     :param model_output_dir:
-        Directory to write the model code to. Will be created if doesn't
+        Directory to write the model code to. It will be created if it doesn't
         exist. Defaults to current directory.
 
     :param model_name:
-        Name of the generated model. If model file name was provided,
-        this defaults to the file name without extension, otherwise
-        the model ID will be used.
+        Name of the generated model module. Defaults to the ID of the model
+        or the model file name without the extension.
 
     :param force_compile:
         Whether to compile the model even if the target folder is not empty,
@@ -63,7 +65,8 @@ def import_petab_problem(
 
     :param kwargs:
         Additional keyword arguments to be passed to
-        :meth:`amici.sbml_import.SbmlImporter.sbml2amici`.
+        :meth:`amici.sbml_import.SbmlImporter.sbml2amici` or
+        :func:`amici.pysb_import.pysb2amici`, depending on the model type.
 
     :return:
         The imported model.

python/sdist/amici/petab/pysb_import.py

@@ -188,7 +188,7 @@ def import_model_pysb(
 
     :param kwargs:
         Additional keyword arguments to be passed to
-        :meth:`amici.pysb_import.pysb2amici`.
+        :func:`amici.pysb_import.pysb2amici`.
     """
     set_log_level(logger, verbose)
 

python/sdist/amici/petab/simulations.py

@@ -54,6 +54,19 @@
 EDATAS = "edatas"
 
 
+__all__ = [
+    "simulate_petab",
+    "LLH",
+    "SLLH",
+    "FIM",
+    "S2LLH",
+    "RES",
+    "SRES",
+    "RDATAS",
+    "EDATAS",
+]
+
+
 @log_execution_time("Simulating PEtab model", logger)
 def simulate_petab(
     petab_problem: petab.Problem,

python/sdist/amici/petab_import.py

@@ -3,6 +3,9 @@
 ------------
 Import a model in the :mod:`petab` (https://github.com/PEtab-dev/PEtab) format
 into AMICI.
+
+.. deprecated:: 0.21.0
+    Use :mod:`amici.petab` instead.
 """
 import warnings
 
@@ -27,4 +30,16 @@
 from .petab.sbml_import import (  # noqa
     _get_fixed_parameters_sbml as get_fixed_parameters,
 )
-from .petab.sbml_import import species_to_parameters
+from .petab.sbml_import import species_to_parameters  # noqa
+
+__all__ = [
+    "get_observation_model",
+    "petab_noise_distributions_to_amici",
+    "petab_scale_to_amici_scale",
+    "check_model",
+    "import_model",
+    "import_model_sbml",
+    "import_petab_problem",
+    "get_fixed_parameters",
+    "species_to_parameters",
+]

python/sdist/amici/petab_import_pysb.py

@@ -1,3 +1,9 @@
+"""
+PEtab import for PySB models
+
+.. deprecated:: 0.21.0
+    Use :mod:`amici.petab.pysb_import` instead.
+"""
 import warnings
 
 from .petab.pysb_import import *  # noqa: F401, F403
@@ -8,3 +14,7 @@
     "Importing amici.petab_import_pysb is deprecated. Use `amici.petab.pysb_import` instead.",
     DeprecationWarning,
 )
+
+__all__ = [
+    "import_model_pysb",
+]

python/sdist/amici/petab_objective.py

@@ -1,3 +1,10 @@
+"""
+Evaluate a PEtab objective function.
+
+.. deprecated:: 0.21.0
+    Use :mod:`amici.petab.simulations` instead.
+"""
+
 # THIS FILE IS TO BE REMOVED - DON'T ADD ANYTHING HERE!
 
 import warnings
@@ -25,3 +32,22 @@
     rescale_sensitivity,
     simulate_petab,
 )
+
+__all__ = [
+    "EDATAS",
+    "FIM",
+    "LLH",
+    "RDATAS",
+    "RES",
+    "S2LLH",
+    "SLLH",
+    "SRES",
+    "aggregate_sllh",
+    "create_edatas",
+    "fill_in_parameters",
+    "create_parameter_mapping",
+    "rdatas_to_measurement_df",
+    "rdatas_to_simulation_df",
+    "rescale_sensitivity",
+    "simulate_petab",
+]

python/sdist/amici/petab_simulate.py

@@ -1,3 +1,9 @@
+"""
+Simulate a PEtab problem
+
+.. deprecated:: 0.21.0
+    Use :mod:`amici.petab.simulator` instead.
+"""
 # THIS FILE IS TO BE REMOVED - DON'T ADD ANYTHING HERE!
 
 import warnings
@@ -8,3 +14,7 @@
 )
 
 from .petab.simulator import PetabSimulator  # noqa: F401
+
+__all__ = [
+    "PetabSimulator",
+]

python/sdist/amici/petab_util.py

@@ -1,4 +1,9 @@
-"""Various helper functions for working with PEtab problems."""
+"""
+Various helper functions for working with PEtab problems.
+
+.. deprecated:: 0.21.0
+    Use :mod:`amici.petab.util` instead.
+"""
 
 # THIS FILE IS TO BE REMOVED - DON'T ADD ANYTHING HERE!
 
@@ -11,3 +16,8 @@
     f"Importing {__name__} is deprecated. Use `amici.petab.util` instead.",
     DeprecationWarning,
 )
+
+__all__ = [
+    "get_states_in_condition_table",
+    "PREEQ_INDICATOR_ID",
+]

python/sdist/amici/swig.py

@@ -97,9 +97,9 @@
         ) in self.mapping:
             value_type_annot = self.mapping[value_type]
             if isinstance(value_type_annot, ast.Constant):
-                return ast.Name(f"Tuple['{value_type_annot.value}']")
+                return ast.Name(f"tuple['{value_type_annot.value}']")
             if isinstance(value_type_annot, ast.Name):
-                return ast.Name(f"Tuple[{value_type_annot.id}]")
+                return ast.Name(f"tuple[{value_type_annot.id}]")
 
         return ast.Constant(old_annot)