docs!: switch to MyST #208
Conversation
Also use the correct package names from PyPI (like dashes instead of underscores)
WARNING: this removes the nbsphinx_prolog on the top on each example page, as there is no equivalent of that in myst-nb https://nbsphinx.readthedocs.io/en/0.8.6/prolog-and-epilog.html
|
Not sure why pre-commit.ci does not autofix the style issues... |
The Controls object is often referenced, but it's not documented in the API.
Also optimizes some of the notebooks for myst-nb (MyST syntax)
|
@ianhi another small doc related thing: could you abbreviate the link to the docs on the about section for the repo to
|
There was a problem hiding this comment.
This is fantastic thank you for all the work! and for the excellent PR/commit messages/explanations! They make it much easier to follow.
@ianhi another small doc related thing: could you abbreviate the link to the docs on the about section for the repo to https://mpl-interactions.rtfd.io (excluding the final slash)?
Sure thing. What benefit does this bring?
| @@ -124,6 +124,10 @@ | |||
| "python": ("https://docs.python.org/3", None), | |||
| } | |||
|
|
|||
| # Settings for copybutton | |||
| copybutton_prompt_is_regexp = True | |||
| copybutton_prompt_text = r">>> |\.\.\. " # doctest | |||
There was a problem hiding this comment.
does this actually come up anywhere? Why not include the full regex including the [In] etc to protect against that in the future
There was a problem hiding this comment.
Yeah good point, there are currently no doctests. But still, once there are (and I encourage adding them, because they can be tested with pytest as well), these lines make the copy button there more convenient.
There was a problem hiding this comment.
Wanted to add the --doctest-modules flag to pytest.ini, but then noticed this 'bug' #210.
There was a problem hiding this comment.
doctest = testing snippets in docstrings and in .md and .rst files? The notebooks that make up the majority of the docs are already included in the test runs.
There was a problem hiding this comment.
Yes, the ones in md and rst files would be doctests too, but I initially only had doctests in the docstrings (that is, the API) in mind. It's in line with #203, where the idea is that the API can serve more as its own documentation as well (with some integrated examples). That said, I now start to wonder how useful doctests are for a matplotlib framework..
Let's move this to #208.
I'll look at this tomorrow. After that are there any other changes you want here? |
Aesthetics 🙌 😉 |
It seems that prettier insists on modifying staged files which |
otherwise it messes with lists that were intentionally indented
|
Check out this pull request on See visual diffs & provide feedback on Jupyter Notebooks. Powered by ReviewNB |
|
Fantastic thank you! @all-contributors please add @redeboer for documentation |
|
I've put up a pull request to add @redeboer! 🎉 |
I see, thanks for looking into this. I don't get though why autofix (which assumingly involves re-staging) did work for black and isort. |
|
Autofix also works for nbqa, it seems: a7885a1. So I guess it's something with Prettier (which is node.js)? |
I think in this case pre-commit ci is handling the git commands, whereas prettier (I think?) essentially is doing something like |
Closes #206
Warning: Notebooks are now rendered with
myst-nb, but this has no equivalent tonbsphinx_prolog, so the prologue message is not visible in the example pages anymore.A solution would be to switch to the sphinx-book-theme for its launch buttons. That requires some more modifications though, so I split that into a follow-up PR (#209).
Some related improvements:
Controllsclass in the APIlinkcheck(see Improve interlinking of the pages #202)