Doc: Cleanup RTD config (#52)

* Add .readthedocs.yaml

* petab

* add_stylesheet

* ipython

* rm doc/editorial_board.rst

* excludes

* link all examples

* set dep versions

* fix docstring

* ignore numpy warnings

* fix docstring

* ignore recommonmark warnings

* Fix collections.Counter issues

* move deps to setup.py

* py38

Author: dweindl

.readthedocs.yaml

@@ -0,0 +1,17 @@
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+version: 2
+
+sphinx:
+   configuration: doc/conf.py
+   fail_on_warning: true
+
+
+python:
+   version: 3.8
+   install:
+   - method: pip
+     path: .
+     extra_requirements:
+        - doc

.rtd_pip_reqs.txt

@@ -4,28 +4,30 @@
 # list see the documentation:
 # https://www.sphinx-doc.org/en/master/usage/configuration.html
 
+import os
+import subprocess
+import sys
+import warnings
+
 # -- Path setup --------------------------------------------------------------
 
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #
-import os
-import sys
 sys.path.insert(0, os.path.abspath('..'))
 
 # -- Project information -----------------------------------------------------
 
 project = 'PEtab'
-copyright = '2018-2021, the PEtab developers'
+copyright = '2018, the PEtab developers'
 author = 'PEtab developers'
 
 # The full version, including alpha/beta/rc tags
 release = 'latest'
 
 # -- Custom pre-build --------------------------------------------------------
 
-import subprocess
 
 subprocess.run(['python', 'md2rst.py'])
 
@@ -49,7 +51,12 @@
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path.
-exclude_patterns = ['build/doctrees', 'build/html']
+exclude_patterns = [
+    'build/doctrees',
+    'build/html',
+    '**.ipynb_checkpoints',
+    'logo/LICENSE.md',
+]
 
 master_doc = 'index'
 
@@ -72,14 +79,21 @@
     '.md': 'markdown',
 }
 
+# ignore numpy warnings
+warnings.filterwarnings("ignore", message="numpy.dtype size changed")
+warnings.filterwarnings("ignore", message="numpy.ufunc size changed")
+# ignore recommonmark warnings
+#  https://github.com/readthedocs/recommonmark/issues/177
+warnings.filterwarnings("ignore",
+                        message="Container node skipped: type=document")
+
 # -- Options for HTML output -------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
 html_theme = 'sphinx_rtd_theme'
-def setup(app):
-    app.add_stylesheet('custom.css')
+
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
@@ -94,3 +108,14 @@ def setup(app):
 }
 
 html_logo = 'logo/PEtab.png'
+
+
+def skip_some_objects(app, what, name, obj, skip, options):
+    """Exclude some objects from the documentation"""
+    if getattr(obj, '__module__', None) == 'collections':
+        return True
+
+
+def setup(app):
+    """Sphinx setup"""
+    app.connect('autodoc-skip-member', skip_some_objects)

doc/conf.py

@@ -10,6 +10,8 @@ The following examples should help to get a better idea of how to use the PEtab
 
    example/example_petablint.ipynb
    example/example_visualization.ipynb
+   example/example_visualization_without_visspec.ipynb
+   example/example_visualization_with_visspec.ipynb
 
 Examples of systems biology parameter estimation problems specified in PEtab
 can be found in the `systems biology benchmark model collection <https://github.com/Benchmarking-Initiative/Benchmark-Models-PEtab>`_.

doc/editorial_board.rst

@@ -530,6 +530,7 @@ def is_scalar_float(x: Any):
     """
     Checks whether input is a number or can be transformed into a number
     via float
+
     :param x:
         input
     :return:

doc/example.rst

@@ -1,6 +1,6 @@
 """Functions for working with the PEtab observables table"""
 
-from _collections import OrderedDict
+from collections import OrderedDict
 from typing import Union, List
 
 import libsbml

petab/lint.py

@@ -380,10 +380,11 @@ def get_model_parameters(sbml_model: libsbml.Model, with_values=False
 
     Arguments:
         sbml_model: SBML model
-        with_values: If false, returns list of SBML model parameter IDs which
-        are not AssignmentRule targets for observables or sigmas. If true,
-        returns a dictionary with those parameter IDs as keys and parameter
-        values from the SBML model as values.
+        with_values:
+            If False, returns list of SBML model parameter IDs which
+            are not AssignmentRule targets for observables or sigmas. If True,
+            returns a dictionary with those parameter IDs as keys and parameter
+            values from the SBML model as values.
     """
     if not with_values:
         return [p.getId() for p in sbml_model.getListOfParameters()

petab/observables.py

@@ -69,6 +69,18 @@ def absolute_links(txt):
       tests_require=['flake8', 'pytest', 'python-libcombine'],
       python_requires='>=3.7.1',
       entry_points=ENTRY_POINTS,
-      extras_require={'reports': ['Jinja2'],
-                      'combine': ['python-libcombine>=0.2.6']},
+      extras_require={
+          'reports': ['Jinja2'],
+          'combine': ['python-libcombine>=0.2.6'],
+          'doc': [
+              'sphinx>=3.5.3',
+              'sphinxcontrib-napoleon>=0.7',
+              'sphinx-markdown-tables>=0.0.15',
+              'sphinx-rtd-theme>=0.5.1',
+              'recommonmark>=0.7.1',
+              'nbsphinx>=0.8.2',
+              'm2r>=0.2.1',
+              'ipython>=7.21.0',
+          ]
+      }
       )