BLD: Replace sphinx-apidoc with sphinx-autosummary

The goal of this commit is to allow building a bit more sensible docs.
Instead of a massive file with modules and submodules and classes all
documented on the same page, this has one top-levelobject
(module, class, or function) documented on each web page, akin to scikitlearn
e.g. https://scikit-learn.org/stable/api/sklearn.multiclass.html

There is one significant practical decision to make: we need to be clear about
from where we expect an object to be imported.  E.g. I've chosen to hide
documentation of modules like sr3.py and instead document all optimizer classes
under pysindy.optimizers.  We can't do it in two places.  This also means
that pysindy/pysindy.py became pysindy/_core.py, so that SINDy is documented
in the main pysindy package namespace.  There's some other small flattening,
but largely, I expect to hide more and more modules with an underscore as time
goes on, so that helper functions don't end up as part of a backwards
compatability contract.

This isn't the final word in the page layouts.  There's a lot more visual
improvements that can be made.  But this commit should solve the technical
problems and allow us to tweak from here.

Author: Jacob-Stevens-Haas

README.rst

@@ -73,7 +73,7 @@ which correctly results in
   y' = 1.000 y
 
 PySINDy provides numerous other features not shown here. We have a variety of tutorials and examples, starting with
-`feature overview <https://pysindy.readthedocs.io/en/latest/examples/1_feature_overview/example.html>`_.
+`generating data and fitting models <examples/tutorial_1/example.html>`_.
 
 
 Getting Help

docs/.gitignore

@@ -0,0 +1 @@
+generated/

docs/api.rst

@@ -0,0 +1,11 @@
+:orphan:
+
+pysindy package
+===============
+
+.. autosummary::
+   :toctree: generated/
+   :template: module.rst
+   :recursive:
+
+   pysindy

docs/conf.py

@@ -14,40 +14,32 @@
 from sphinx.util.docutils import SphinxDirective
 
 author = "dynamicslab"
-project = "pysindy"  # package name
-
-
-# no need to edit below this line
-
+project = "pysindy"
 copyright = f"2020, {author}"
-
 module = importlib.import_module(project)
 version = release = getattr(module, "__version__")
 
 master_doc = "index"
 
 extensions = [
-    "nbsphinx",
-    "sphinxcontrib.apidoc",
     "sphinx.ext.autodoc",
-    "sphinx.ext.todo",
-    "sphinx.ext.viewcode",
     "sphinx.ext.autosummary",
+    "nbsphinx",
+    "sphinx.ext.todo",
     "sphinx.ext.napoleon",
+    "sphinx.ext.viewcode",
     "sphinx.ext.mathjax",
     "sphinx.ext.intersphinx",
     "IPython.sphinxext.ipython_console_highlighting",
 ]
 
 nb_execution_mode = "off"
 
-apidoc_module_dir = f"../{project}"
-apidoc_excluded_paths = ["tests"]
-apidoc_toc_file = False
+templates_path = ["templates"]
+autosummary_generate = True
+autosummary_ignore_module_all = False
 
-autodoc_default_options = {"members": True}
-autodoc_member_order = "bysource"
-autoclass_content = "init"
+autoclass_content = "both"
 
 language = "en"
 
@@ -69,10 +61,22 @@
 html_sourcelink_suffix = ""
 
 intersphinx_mapping = {
-    "derivative": ("https://derivative.readthedocs.io/en/latest/", None),
-    "sklearn": ("https://scikit-learn.org/stable/", None),
+    "derivative": ("https://derivative.readthedocs.io/en/latest", None),
+    "sklearn": ("https://scikit-learn.org/stable", None),
+    "numpy": ("https://numpy.org/doc/stable", None),
 }
 
+show_warning_types = True
+suppress_warnings = [
+    "ref.python",
+    "ref.exc",
+    "ref.class",
+    "ref.obj",
+    "ref.meth",
+    "ref.any",
+    "ref",
+]
+
 # -- Extensions to the  Napoleon GoogleDocstring class ---------------------
 # michaelgoerz.net/notes/extending-sphinx-napoleon-docstring-sections.html
 from sphinx.ext.napoleon.docstring import GoogleDocstring  # noqa: E402

docs/index.rst

@@ -12,7 +12,7 @@
    Contributing <contributing>
    Using pysindy in academia <academic>
    Object Model <objects>
-   API Documentation <api/pysindy>
+   API Documentation <generated/pysindy>
 
 .. toctree::
    :maxdepth: 1

docs/templates/class.rst

@@ -0,0 +1,34 @@
+{{ fullname | escape | underline}}
+
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ objname }}
+   :members:
+   :special-members: __call__, __add__, __mul__
+
+   {% block methods %}
+   {% if methods %}
+   .. rubric:: {{ _('Methods') }}
+
+   .. autosummary::
+      :nosignatures:
+   {% for item in methods %}
+      {%- if not item.startswith('_') and item not in inherited_members%}
+      ~{{ name }}.{{ item }}
+      {%- endif -%}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block attributes %}
+   {% if attributes %}
+   .. rubric:: {{ _('Attributes') }}
+
+   .. autosummary::
+   {% for item in attributes %}
+      {%- if not item.startswith('_') and item not in inherited_members%}
+      ~{{ name }}.{{ item }}
+      {%- endif -%}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}

docs/templates/module.rst

@@ -0,0 +1,66 @@
+{{ fullname | escape | underline}}
+
+.. automodule:: {{ fullname }}
+
+   {% block attributes %}
+   {% if attributes %}
+   .. rubric:: Module attributes
+
+   .. autosummary::
+      :toctree:
+   {% for item in attributes %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block functions %}
+   {% if functions %}
+   .. rubric:: {{ _('Functions') }}
+
+   .. autosummary::
+      :toctree:
+      :nosignatures:
+   {% for item in functions %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block classes %}
+   {% if classes %}
+   .. rubric:: {{ _('Classes') }}
+
+   .. autosummary::
+      :toctree:
+      :template: class.rst
+      :nosignatures:
+   {% for item in classes %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block exceptions %}
+   {% if exceptions %}
+   .. rubric:: {{ _('Exceptions') }}
+
+   .. autosummary::
+      :toctree:
+   {% for item in exceptions %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+{% block modules %}
+{% if modules %}
+.. autosummary::
+   :toctree:
+   :template: module.rst
+   :recursive:
+{% for item in modules %}
+   {{ item }}
+{%- endfor %}
+{% endif %}
+{% endblock %}

pyproject.toml

@@ -57,7 +57,7 @@ docs = [
     "pandoc",
     "requests",
     "sphinx-rtd-theme",
-    "sphinx==7.4.7",
+    "sphinx==8.2.3",
     "pyyaml",
     "sphinxcontrib-apidoc",
 ]

pysindy/__init__.py

@@ -11,8 +11,8 @@
 from . import optimizers
 from . import deeptime
 from . import utils
-from .pysindy import SINDy
-from .pysindy import AxesArray
+from ._core import SINDy
+from ._core import AxesArray
 from .differentiation import BaseDifferentiation
 from .differentiation import FiniteDifference
 from .differentiation import SpectralDerivative
@@ -63,9 +63,11 @@
     pass
 
 
-__all__ = ["SINDy", "AxesArray"]
-__all__.extend(differentiation.__all__)
-__all__.extend(feature_library.__all__)
-__all__.extend(optimizers.__all__)
-__all__.extend(["utils"])
-__all__.extend(["deeptime"])
+__all__ = [
+    "SINDy",
+    "differentiation",
+    "feature_library",
+    "optimizers",
+    "deeptime",
+    "utils",
+]

pysindy/pysindy.py renamed to pysindy/_core.py

@@ -48,7 +48,6 @@ class _BaseSINDy(BaseEstimator, ABC):
 
     feature_library: BaseFeatureLibrary
     optimizer: _BaseOptimizer
-    discrete_time: bool
     model: Pipeline
     # Hacks to remove later
     feature_names: Optional[list[str]]
@@ -178,31 +177,31 @@ class SINDy(_BaseSINDy):
 
     Parameters
     ----------
-    optimizer : optimizer object, optional
+    optimizer
         Optimization method used to fit the SINDy model. This must be a class
         extending :class:`pysindy.optimizers.BaseOptimizer`.
-        The default is :class:`STLSQ`.
+        The default is :class:`pysindy.optimizers.STLSQ`.
 
-    feature_library : feature library object, optional
+    feature_library
         Feature library object used to specify candidate right-hand side features.
         This must be a class extending
         :class:`pysindy.feature_library.base.BaseFeatureLibrary`.
-        The default option is :class:`PolynomialLibrary`.
+        The default option is :class:`pysindy.feature_library.PolynomialLibrary`.
 
-    differentiation_method : differentiation object, optional
+    differentiation_method
         Method for differentiating the data. This must be a class extending
-        :class:`pysindy.differentiation_methods.base.BaseDifferentiation` class.
+        :class:`pysindy.differentiation.base.BaseDifferentiation` class.
         The default option is centered difference.
 
-    discrete_time : boolean, optional (default False)
+    discrete_time
         If True, dynamical system is treated as a map. Rather than predicting
         derivatives, the right hand side functions step the system forward by
         one time step. If False, dynamical system is assumed to be a flow
         (right-hand side functions predict continuous time derivatives).
 
     Attributes
     ----------
-    model : ``sklearn.multioutput.MultiOutputRegressor`` object
+    model : ``sklearn.multioutput.MultiOutputRegressor``
         The fitted SINDy model.
 
     n_input_features_ : int