Doc: Cleanup / fixup (#53)

* Doc: Intersphinx and source references

* some docstring fixes

* fix some more

* sphinx-autodoc-typehints

* Revert "sphinx-autodoc-typehints"

This reverts commit 997f07f.

Author: dweindl

doc/conf.py

@@ -39,12 +39,21 @@
 extensions = [
     'sphinx.ext.napoleon',
     'sphinx.ext.autodoc',
-    'recommonmark',
     'sphinx.ext.autosummary',
+    'sphinx.ext.intersphinx',
+    'sphinx.ext.viewcode',
+    'recommonmark',
     'sphinx_markdown_tables',
     'nbsphinx',
 ]
 
+intersphinx_mapping = {
+    'pandas': ('https://pandas.pydata.org/docs/', None),
+    'numpy': ('https://numpy.org/devdocs/', None),
+    'sympy': ('https://docs.sympy.org/latest/', None),
+    'python': ('https://docs.python.org/3', None),
+}
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 

petab/composite_problem.py

@@ -15,7 +15,7 @@ class CompositeProblem:
 
     Attributes:
         problems:
-            List ``petab.Problems``
+            List of :py:class:`petab.Problem` s
         parameter_df:
             PEtab parameter DataFrame
     """

petab/conditions.py

@@ -61,8 +61,8 @@ def create_condition_df(parameter_ids: Iterable[str],
         parameter_ids: the columns
         condition_ids: the rows
     Returns:
-        A ``pandas.DataFrame`` with empty given rows and columns and all nan
-        values
+        A :py:class:`pandas.DataFrame` with empty given rows and columns and
+        all nan values
     """
 
     condition_ids = [] if condition_ids is None else list(condition_ids)

petab/core.py

@@ -355,7 +355,8 @@ def unique_preserve_order(seq: Sequence) -> List:
     """Return a list of unique elements in Sequence, keeping only the first
     occurrence of each element
 
-    seq: Sequence to prune
+    Parameters:
+        seq: Sequence to prune
 
     Returns:
         List of unique elements in ``seq``

petab/lint.py

@@ -448,7 +448,7 @@ def assert_parameter_prior_type_is_valid(
         parameter_df: PEtab parameter table
 
     Raises:
-        AssertionError in case of invalid prior
+        AssertionError: in case of invalid prior
     """
     for col in [INITIALIZATION_PRIOR_TYPE, OBJECTIVE_PRIOR_TYPE]:
         if col not in parameter_df.columns:
@@ -468,7 +468,7 @@ def assert_parameter_prior_parameters_are_valid(
         parameter_df: PEtab parameter table
 
     Raises:
-        AssertionError in case of invalide prior parameters
+        AssertionError: in case of invalid prior parameters
     """
     prior_type_cols = [INITIALIZATION_PRIOR_TYPE,
                        OBJECTIVE_PRIOR_TYPE]
@@ -534,7 +534,7 @@ def is_scalar_float(x: Any):
     :param x:
         input
     :return:
-        True if is or can be converted to number, False otherwise.
+        ``True`` if is or can be converted to number, ``False`` otherwise.
     """
     if isinstance(x, numbers.Number):
         return True

petab/parameter_mapping.py

@@ -48,7 +48,8 @@ def get_optimization_to_simulation_parameter_mapping(
     Create list of mapping dicts from PEtab-problem to SBML parameters.
 
     Mapping can be performed in parallel. The number of threads is controlled
-    by the environment variable with the name of petab.ENV_NUM_THREADS.
+    by the environment variable with the name of
+    :py:data:`petab.ENV_NUM_THREADS`.
 
     Parameters:
         condition_df, measurement_df, parameter_df, observable_df:
@@ -78,9 +79,9 @@ def get_optimization_to_simulation_parameter_mapping(
         Parameter value and parameter scale mapping for all conditions.
 
         The length of the returned array is the number of unique combinations
-        of ``simulationConditionId``s and ``preequilibrationConditionId``s from
-        the measurement table. Each entry is a tuple of four dicts of length
-        equal to the number of model parameters.
+        of ``simulationConditionId`` s and ``preequilibrationConditionId`` s
+        from the measurement table. Each entry is a tuple of four dicts of
+        length equal to the number of model parameters.
         The first two dicts map simulation parameter IDs to optimization
         parameter IDs or values (where values are fixed) for preequilibration
         and simulation condition, respectively.
@@ -160,7 +161,9 @@ def _map_condition_arg_packer(
 def _map_condition(packed_args):
     """Helper function for parallel condition mapping.
 
-    For arguments see get_optimization_to_simulation_parameter_mapping"""
+    For arguments see
+    :py:func:`get_optimization_to_simulation_parameter_mapping`.
+    """
 
     (condition, measurement_df, condition_df, parameter_df, sbml_model,
      simulation_parameters, warn_unmapped, scaled_parameters,
@@ -264,7 +267,7 @@ def get_parameter_mapping_for_condition(
         to mapped parameters IDs to be estimated or to filled-in values in case
         of non-estimated parameters.
         Second dictionary mapping model parameter IDs to their scale.
-        NaN is used where no mapping exists.
+        ``NaN`` is used where no mapping exists.
     """
     _perform_mapping_checks(
         cur_measurement_df,
@@ -323,7 +326,7 @@ def _apply_output_parameter_overrides(
 
     Arguments:
         mapping: parameter mapping dict as obtained from
-            ``get_parameter_mapping_for_condition``
+            :py:func:`get_parameter_mapping_for_condition`.
         cur_measurement_df:
             Subset of the measurement table for the current condition
     """
@@ -376,7 +379,7 @@ def _apply_condition_parameters(par_mapping: ParMappingDict,
     table parameter values (in-place).
 
     Arguments:
-        par_mapping: see get_parameter_mapping_for_condition
+        par_mapping: see :py:func:`get_parameter_mapping_for_condition`
         condition_id: ID of condition to work on
         condition_df: PEtab condition table
     """
@@ -410,7 +413,8 @@ def _apply_parameter_table(par_mapping: ParMappingDict,
 
     Arguments:
         par_mapping:
-            mapping dict obtained from ``get_parameter_mapping_for_condition``
+            mapping dict obtained from
+            :py:func:`get_parameter_mapping_for_condition`
         parameter_df:
             PEtab parameter table
     """
@@ -495,7 +499,7 @@ def handle_missing_overrides(mapping_par_opt_to_par_sim: ParMappingDict,
 
     Parameters:
         mapping_par_opt_to_par_sim:
-            Output of get_parameter_mapping_for_condition
+            Output of :py:func:`get_parameter_mapping_for_condition`
         warn:
             If True, log warning regarding unmapped parameters
         condition_id:
@@ -538,10 +542,10 @@ def merge_preeq_and_sim_pars_condition(
     Arguments:
         condition_map_preeq, condition_map_sim:
             Parameter mapping as obtained from
-            `get_parameter_mapping_for_condition`
+            :py:func:`get_parameter_mapping_for_condition`
         condition_scale_map_preeq, condition_scale_map_sim:
             Parameter scale mapping as obtained from
-            `get_get_scale_mapping_for_condition`
+            :py:func:`get_parameter_mapping_for_condition`
         condition: Condition identifier for more informative error messages
     """
     if not condition_map_preeq:
@@ -610,9 +614,10 @@ def merge_preeq_and_sim_pars(
     Parameters:
         parameter_mappings:
             As returned by
-            petab.get_optimization_to_simulation_parameter_mapping
+            :py:func:`petab.get_optimization_to_simulation_parameter_mapping`.
         scale_mappings:
-            As returned by petab.get_optimization_to_simulation_scale_mapping.
+            As returned by
+            :py:func:`petab.get_optimization_to_simulation_parameter_mapping`.
 
     Returns:
         The parameter and scale simulation mappings, modified and checked.

petab/parameters.py

@@ -364,8 +364,7 @@ def scale(parameter: numbers.Number, scale_str: 'str') -> numbers.Number:
             One of 'lin' (synonymous with ''), 'log', 'log10'.
 
     Returns:
-        parameter:
-            The scaled parameter.
+        The scaled parameter.
     """
 
     if scale_str == LIN or not scale_str:
@@ -387,8 +386,7 @@ def unscale(parameter: numbers.Number, scale_str: 'str') -> numbers.Number:
             One of 'lin' (synonymous with ''), 'log', 'log10'.
 
     Returns:
-        parameter:
-            The unscaled parameter.
+        The unscaled parameter.
     """
 
     if scale_str == LIN or not scale_str:

petab/problem.py

@@ -233,13 +233,13 @@ def from_folder(folder: str, model_name: str = None) -> 'Problem':
     def from_combine(filename: str) -> 'Problem':
         """Read PEtab COMBINE archive (http://co.mbine.org/documents/archive).
 
-        See also ``create_combine_archive``.
+        See also :py:func:`petab.create_combine_archive`.
 
         Arguments:
             filename: Path to the PEtab-COMBINE archive
 
         Returns:
-            A ``petab.Problem`` instance.
+            A :py:class:`petab.Problem` instance.
         """
         # function-level import, because module-level import interfered with
         # other SWIG interfaces
@@ -291,8 +291,8 @@ def to_files(self,
             yaml_file: YAML file destination
 
         Raises:
-            ValueError: If a destination was provided for a non-existing
-            entity.
+            ValueError:
+                If a destination was provided for a non-existing entity.
         """
 
         if sbml_file:
@@ -350,26 +350,27 @@ def get_optimization_parameters(self):
         """
         Return list of optimization parameter IDs.
 
-        See ``petab.parameters.get_optimization_parameters``.
+        See :py:func:`petab.parameters.get_optimization_parameters`.
         """
         return parameters.get_optimization_parameters(self.parameter_df)
 
     def get_optimization_parameter_scales(self):
         """
         Return list of optimization parameter scaling strings.
 
-        See ``petab.parameters.get_optimization_parameters``.
+        See :py:func:`petab.parameters.get_optimization_parameters`.
         """
         return parameters.get_optimization_parameter_scaling(self.parameter_df)
 
     def get_model_parameters(self):
-        """See `petab.sbml.get_model_parameters`"""
+        """See :py:func:`petab.sbml.get_model_parameters`"""
         return sbml.get_model_parameters(self.sbml_model)
 
     def get_observables(self, remove: bool = False):
         """
         Returns dictionary of observables definitions.
-        See `assignment_rules_to_dict` for details.
+
+        See :py:func:`petab.assignment_rules_to_dict` for details.
         """
         warn("This function will be removed in future releases.",
              DeprecationWarning)
@@ -386,6 +387,7 @@ def get_sigmas(self, remove: bool = False):
         """
         Return dictionary of observableId => sigma as defined in the SBML
         model.
+
         This does not include parameter mappings defined in the measurement
         table.
         """
@@ -396,7 +398,7 @@ def get_sigmas(self, remove: bool = False):
 
     def get_noise_distributions(self):
         """
-        See `get_noise_distributions`.
+        See :py:func:`petab.get_noise_distributions`.
         """
         return measurements.get_noise_distributions(
             measurement_df=self.measurement_df)
@@ -633,7 +635,7 @@ def get_optimization_to_simulation_parameter_mapping(
     def create_parameter_df(self, *args, **kwargs):
         """Create a new PEtab parameter table
 
-        See create_parameter_df
+        See :py:func:`create_parameter_df`.
         """
         return parameters.create_parameter_df(
             self.sbml_model,
@@ -645,7 +647,7 @@ def create_parameter_df(self, *args, **kwargs):
     def sample_parameter_startpoints(self, n_starts: int = 100):
         """Create starting points for optimization
 
-        See sample_parameter_startpoints
+        See :py:func:`petab.sample_parameter_startpoints`.
         """
         return sampling.sample_parameter_startpoints(
             self.parameter_df, n_starts=n_starts)