Doc: pypesto.select xrefs + add select.postprocessors (#1146)

Fixes formatting, adds proper cross-references, and add pypesto.select.postprocessors to the sphinx API doc.

doc/api.rst

@@ -23,6 +23,7 @@ API reference
    pypesto.result
    pypesto.sample
    pypesto.select
+   pypesto.select.postprocessors
    pypesto.startpoint
    pypesto.store
    pypesto.visualize

pypesto/select/model_problem.py

@@ -32,21 +32,21 @@ class ModelProblem:
         calibrated.
     minimize_options:
         Keyword argument options that will be passed on to
-        `pypesto.optimize.minimize`.
+        :func:`pypesto.optimize.minimize`.
     minimize_result:
         A pyPESTO result with an optimize result.
     model:
         A PEtab Select model.
     model_id:
         The ID of the PEtab Select model.
     objective_customizer:
-        A method that takes a `pypesto.objective.AmiciObjective` as
+        A method that takes a :class:`pypesto.objective.AmiciObjective` as
         input, and makes changes to the objective in-place.
     postprocessor:
-        A method that takes a `ModelSelectionProblem` as input. For
+        A method that takes a :class:`ModelSelectionProblem` as input. For
         example, this can be a function that generates a waterfall
         plot. This postprocessor is applied at the end of the
-        `ModelProblem.set_result` method.
+        :meth:`ModelProblem.set_result` method.
     pypesto_problem:
         The pyPESTO problem for the model.
     valid:
@@ -75,9 +75,9 @@ def __init__(
         Parameters
         ----------
         autorun:
-            If `False`, the model parameters will not be estimated. Allows
-            users to manually call pypesto.minimize with custom options,
-            then`set_result()`.
+            If ``False``, the model parameters will not be estimated. Allows
+            users to manually call ``pypesto.minimize`` with custom options,
+            then :meth:`set_result()`.
 
         TODO: constraints
         """

pypesto/select/postprocessors.py

@@ -10,22 +10,30 @@
 from ..C import TYPE_POSTPROCESSOR
 from .model_problem import ModelProblem
 
+__all__ = [
+    'model_id_binary_postprocessor',
+    'multi_postprocessor',
+    'report_postprocessor',
+    'save_postprocessor',
+    'waterfall_plot_postprocessor',
+]
+
 
 def multi_postprocessor(
     problem: ModelProblem,
     postprocessors: List[TYPE_POSTPROCESSOR] = None,
 ):
     """Combine multiple postprocessors into a single postprocessor.
 
-    See `save_postprocessor` for usage hints.
+    See :meth:`save_postprocessor` for usage hints.
 
     Parameters
     ----------
     problem:
         A model selection :class:`ModelProblem` that has been optimized.
     postprocessors:
         A list of postprocessors, which will be sequentially applied to the
-        optimized model `problem`.
+        optimized model ``problem``.
         The location where results will be stored.
     """
     for postprocessor in postprocessors:
@@ -38,7 +46,7 @@ def waterfall_plot_postprocessor(
 ):
     """Produce a waterfall plot.
 
-    See `save_postprocessor` for usage hints and argument documentation.
+    See :meth:`save_postprocessor` for usage hints and argument documentation.
     """
     visualize.waterfall(problem.minimize_result)
     plot_output_path = Path(output_path) / (problem.model.model_hash + ".png")
@@ -53,9 +61,11 @@ def save_postprocessor(
     """Save the parameter estimation result.
 
     When used, first set the output folder for results, e.g. with
-    `functools.partial`. This is because postprocessors should take only a
+    :func:`functools.partial`. This is because postprocessors should take only a
     single parameter: an optimized model.
+
     .. code-block:: python
+
        from functools import partial
        output_path = 'results'
        pp = partial(save_postprocessor, output_path=output_path)
@@ -71,7 +81,7 @@ def save_postprocessor(
     output_path:
         The location where output will be stored.
     use_model_hash:
-        Whether the filename should use the model hash. Defaults to `False`,
+        Whether the filename should use the model hash. Defaults to ``False``,
         in which case the model ID is used instead.
     """
     stem = problem.model.model_id
@@ -86,14 +96,14 @@ def save_postprocessor(
 def model_id_binary_postprocessor(problem: ModelProblem):
     """Change a PEtab Select model ID to a binary string.
 
-    Changes the model ID in-place to be a string like `M_ijk`, where
-    `i`, `j`, `k`, etc. are `1` if the parameter in that position is estimated,
-    or `0` if the parameter is fixed.
+    Changes the model ID in-place to be a string like ``M_ijk``, where
+    ``i``, ``j``, ``k``, etc. are ``1`` if the parameter in that position is estimated,
+    or ``0`` if the parameter is fixed.
 
-    To ensure that other postprocessors (e.g. `report_postprocessor`) use this
-    new model ID, when in use with a `multi_postprocessor`, ensure this is
-    before the other postprocessors in the `postprocessors` argument of
-    `multi_postprocessor`.
+    To ensure that other postprocessors (e.g. :func:`report_postprocessor`) use this
+    new model ID, when in use with a :func:`multi_postprocessor`, ensure this is
+    before the other postprocessors in the ``postprocessors`` argument of
+    :func:`multi_postprocessor`.
 
     Parameters
     ----------

pypesto/select/problem.py

@@ -12,19 +12,19 @@ class Problem:
     """Handles use of a model selection algorithm.
 
     Handles model selection. Usage involves initialisation with a model
-    specifications file, and then calling the `select()` method to perform
+    specifications file, and then calling the :meth:`select` method to perform
     model selection with a specified algorithm and criterion.
 
     Attributes
     ----------
     calibrated_models:
         Storage for all calibrated models. A dictionary, where keys are
-        model hashes, and values are `petab_select.Model` objects.
+        model hashes, and values are :class:`petab_select.Model` objects.
     newly_calibrated_models:
         Storage for models that were calibrated in the previous iteration of
-        model selection. Same type as `calibrated_models`.
+        model selection. Same type as ``calibrated_models``.
     method_caller:
-        A `MethodCaller`, used to run a single iteration of a model
+        A :class:`MethodCaller`, used to run a single iteration of a model
         selection method.
     model_postprocessor:
         A method that is applied to each model after calibration.
@@ -53,7 +53,7 @@ def __init__(
     def create_method_caller(self, **kwargs) -> MethodCaller:
         """Create a method caller.
 
-        `args` and `kwargs` are passed to the `MethodCaller` constructor.
+        ``kwargs`` are passed to the :class:`MethodCaller` constructor.
 
         Returns
         -------
@@ -117,7 +117,7 @@ def select(
         The result is the selected model for the current run, independent of
         previous selected models.
 
-        `kwargs` are passed to the `MethodCaller` constructor.
+        ``kwargs`` are passed to the :class:`MethodCaller` constructor.
 
         Returns
         -------
@@ -162,10 +162,10 @@ def select_to_completion(
     ) -> List[Model]:
         """Run an algorithm until an exception `StopIteration` is raised.
 
-        `kwargs` are passed to the `MethodCaller` constructor.
+        ``kwargs`` are passed to the :class:`MethodCaller` constructor.
 
-        An exception `StopIteration` is raised by
-        `pypesto.select.method.MethodCaller.__call__` when no candidate models
+        An exception ``StopIteration`` is raised by
+        :meth:`pypesto.select.method.MethodCaller.__call__` when no candidate models
         are found.
 
         Returns
@@ -218,7 +218,7 @@ def multistart_select(
         (but then the same model could be repeatedly calibrated, if the
         calibrations start before any have stopped).
 
-        `kwargs` are passed to the `MethodCaller` constructor.
+        ``kwargs`` are passed to the :class:`MethodCaller` constructor.
 
         Parameters
         ----------