Skip to content

Conversation

Jacob-Stevens-Haas
Copy link
Member

@Jacob-Stevens-Haas Jacob-Stevens-Haas commented Sep 13, 2025

Major reorganization of documentation. The goals here were to:

  1. Make the main page README.rst more succinct
  2. Sort current guidance according to divio's documentation system, which distinguishes between tutorials, How-To guides, explanation articles, and API documentation
  3. Organize the API section so there's one class or one package per page, like scikitlearn (example), without redundant documentation (e.g. SINDy object currently documented both as pysindy.SINDy and pysindy.pysindy.SINDy. Don't do this. Also, don't document individual modules whose only purpose is to export a class to the containing package, e.g. pysindy.differentiation.finite_difference)

A few things I especially want feedback on:

  1. I'd like to slowly remove 1_feature_overview, since it can fit better now as small pieces in class docstrings
  2. How do people feel about making the modules whose main purpose is to export a single class private, e.g. pysindy.optimizers.constrained_sr3 becomes here pysindy.optimizers._constrained_sr3, but the ConstrainedSR3 object is still documented in pysindy.optimizers (and still importable both as from pysindy import ConstrainedSR3 and from pysindy.optimizers import ConstrainedSR3)?
  3. I added a citation.cff so its possible to cite the repository as well as the JOSS papers. I think a JOSS paper is the next step at this point, but there's enough in the repo that isn't in a JOSS paper that someone might want to cite. I also added an explanation guide "pysindy in academia" that takes the citation section from the former README.rst and adds other sections about dependency management and adding your method to pysindy.

Some considerations and future work:

  1. switching from sphinx-apidoc to sphinx-autosummary generates a lot more reference crosslinks. This is good for users, but causes a lot more warnings when docsctrings have RST mistakes. As a result, a lot of these warnings are ignored for the interim. Along these lines, I'd also like to find a way to remove some of the inherited methods, e.g. set_fit_request(), a metadata method that every BaseEstimator has.
  2. This PR also required upgrading to a version of sphinx that does not yet have a supporting nbsphinx version. This doesn't cause issues locally besides a pip warning, but theoretically could cause an issue if someone were to add problematic documentation before a supporting nbsphinx version.
  3. Long term, I'd like to move more of the grand notebooks to the Research section, rather than the How-To section. Ideally, the how-to section runs faster and so can be tested/kept up to date with the master branch. Leave the impressive results that take 20 min to run in the research section.
  4. I'd like to combine tips.rst, the flowchart from the old README, and some of the info from Alan's youtube notebook into a third tutorial that does a brief overview of "how to choose model components".

@yyexela I know I promised before graduation that I would fix the pysindy docs sometime this summer - here you go.

Todo

Also bump python version and add myself to a few repo email links
Also fix typo in rummary.rst
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.
Copy link

codecov bot commented Sep 13, 2025

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 95.03%. Comparing base (0d5f6cf) to head (fb7fd28).
⚠️ Report is 1 commits behind head on master.

Additional details and impacted files
@@            Coverage Diff             @@
##           master     #647      +/-   ##
==========================================
- Coverage   95.04%   95.03%   -0.01%     
==========================================
  Files          39       38       -1     
  Lines        4114     4106       -8     
==========================================
- Hits         3910     3902       -8     
  Misses        204      204              

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

1 participant