Fix documentation after PEtab refactoring

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,38 @@ 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
+
+    # 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,17 @@
 # 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 (
+    rdatas_to_measurement_df,
+    rdatas_to_simulation_df,
+    simulate_petab,
+)
+
+__all__ = [
+    "import_petab_problem",
+    "simulate_petab",
+    "rdatas_to_simulation_df",
+    "rdatas_to_measurement_df",
+]

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_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",
+]