docs: improve cross-referencing with intersphinx

[redeboer]

Closes #202

The commit 911ea15 is opinionated: it switches from autosummary to sphinx-apidoc.

• Advantage: inherited members get documented as well and the API follows the code more closely (like if you add a new function, this set-up will automatically let it appear in the API).
• Downside: the main API page looks less nice (can be improved a bit with jinja templates) and the pages are split up per module, not per function.

The commit can be reverted/kicked out if the disadvantages outweigh the advantages.

[redeboer]

Another idea: switch to MyST. It is a superset of restructurettext and also allows the source code for the documentation to be formatted (with Prettier). More importantly, with MySt, Jupyter notebooks can also make use of intersphinx.

[ianhi]

Thanks for doing this! Looks great overall. I had a few questions that I left as review comments but otherwise all 👍 from me.

---

Another idea: switch to MyST. It is a superset of restructurettext and also allows the source code for the documentation to be formatted (with Prettier). More importantly, with MySt, Jupyter notebooks can also make use of intersphinx.

I have been wanting to do this for awhile but never got to it. Is it easy to switch over and get working on RTD? Also what's the breakdown of MYST vs jupyterbook they can both be used to generate docs and book builds on myst? Finally, would this be in addition to this PR or in-place of?

[ianhi]

any reason to remove this?

[redeboer]

__all__ determines which functions are rendered in the API by sphinx-apidoc (and I guess autosummary too). If it's removed, all public members are included. The drawback: SliderBase is now imported as well if you use from mpl_interactions.widgets import *. That * syntax should be avoided though.

Why did I remove it, and include SliderBase? Sphinx-apidoc generates links to the base classes as well:

If those base classes are not available in the API, Sphinx will just raise some warnings. But I think those warnings should be avoided (hence 0efc4e0 and aafbcb0), so I included the SliderBase class. As an alternative, we can list it under nitpicky_ignore and put back the __all__.

[ianhi]

Would using tox then be the best way to start rebuilding the docs? If yes then we should also update https://mpl-interactions.readthedocs.io/en/stable/Contributing.html

[redeboer]

Yeah sorry, it's only later that I notice the make watch you defined
https://github.com/ianhi/mpl-interactions/blob/2eeda96afe6d2d9e6c7354818e7966f0f8a7ad43/docs/Makefile#L22-L23

I personally prefer tox though (it's basically a wrapper around make), because you can run it from any directory in the repo. And in a way, you can use it as local CI.

[ianhi]

Also I'm the creator/maintainer of https://github.com/matplotlib/matplotlib-extension-cookiecutter so I'll happily merge any similar changes there if you want to contribute them (or any other opinions you have about how that should work)

[redeboer]

Also I'm the creator/maintainer of https://github.com/matplotlib/matplotlib-extension-cookiecutter so I'll happily merge any similar changes there if you want to contribute them (or any other opinions you have about how that should work)

Ah yes, you mentioned. Ok, I'll keep an eye on it.
This PR was partially motivated while trying out #201 though and because I noticed intersphinx didn't work well with the API of mpl-interaction.

[redeboer]

I have been wanting to do this for awhile but never got to it. Is it easy to switch over and get working on RTD? Also what's the breakdown of MYST vs jupyterbook they can both be used to generate docs and book builds on myst? Finally, would this be in addition to this PR or in-place of?

Oh and, good to hear! Nah can be done later on. That would indeed be a next 'upgrade'. For clarity:

• MyST is just a Markdown flavour that has all functionality of restructured text (see myst-parser).
• Then there is myst-nb, which extends that to Jupyter notebooks and can replace nbsphinx
• Jupyter book is kind of an easier way to document things with notebooks and markdown files only, but it hides all the sphinx stuff and is therefore (afaik) less suitable for documenting a python package.
• sphinx-book-theme mitigates that: you keep the same set-up, but get the fancy layout.

I think myst-nb and sphinx-book-theme can be implemented separately from switching to myst files.

[ianhi]

Awesome - thanks for the explanation! Are you happy with where this is now?

[redeboer]

Awesome - thanks for the explanation! Are you happy with where this is now?

Yep, looks fine I think.
Perhaps the contributing section needs to be rewritten a bit, but what is written there now is still valid. I could write some words there later, perhaps it's better to tackle #203 (comment) first.

[ianhi]

Perhaps the contributing section needs to be rewritten a bit, but what is written there now is still valid. I could write some words there later, perhaps it's better to tackle #203 (comment) first.

Yup. That sounds fine, plus I think the way described there will still work.

Thanks again!