Promote mpltype Sphinx role to a public extension #28289
Conversation
github-actions
bot
added
topic: sphinx extension
Documentation: build
|
Re: domain. As long as we can declare this non-public (use for inherited docstrings, but not in 3rd party code) we are still free to change the role names in the future, which means, we can wait until the (rather unlikely) case of a conflict with the global names happen and only then switch to domains. |
|
I am wary of saying things are private without a technical (or very obvious naming) way for the user to tell at the point they are using it. |
|
Well, it’s not an average user. Affected are only downstream projects that inherit from our classes and generate documentation. Maybe we could/should have guidelines for them anyway. I‘m hesitant to make the roles public unconditionally because they are primarily intended for internal use. Making them public would make it more difficult to make any changes. |
When projects derive from our types, but don't override all the docstrings, they may want to use these extensions so that their docs build.
|
I added an API change note now, but did not add this anywhere to our docs otherwise. |
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
|
|
||
| For third-party packages that derive types from Matplotlib, our use of custom roles may | ||
| prevent Sphinx from building their docs. These custom Sphinx roles are now public solely |
There was a problem hiding this comment.
We can be more explicit here:
- explain the problem: roles in inherited docstings
- Explicitly write down the exceptions for all our roles („you may see one on the following exceptions). Since we cannot influence the exception messages and they are not telling by themselves, people searching for the message string is their only way forward. We thus should have the stings found in our docs (and that hopefully later also via google).
- State that the addition of the extension should be used to solve the inherited docstring issue, but people should not use these roles explicitly in their docs. (Or rather, we don’t give any guarantees on these. - It might still be convenient to use them, but people should be aware that their docs may break in the future and they might have to adapt, which is not the end of the world for doc builds).
There was a problem hiding this comment.
Maybe move the bulk of the explanation to the roles module docstring and give only a very brief summary here, linking to the module docs. That way, it’s easier to update the docs later.
|
@QuLogic I took the liberty to push a commit with the above suggested changes. Feel free to adapt as you see fit. |
…289-on-v3.9.x Backport PR #28289 on branch v3.9.x (Promote mpltype Sphinx role to a public extension)
1. Fixes Cython.Coverage.Plugin did not provide a file reporter for numpy/__init__.cython-30.pxd" error that shows up in CI by adding a NumPy omit 2. Fixes warning (raised as errors) in sphinx docs build from our inherited matplotlib Axes. We override the offending method because the custom sphinx roles implemented by matplotlib (see matplotlib/matplotlib#28289) don't resolve all the warnings (we still get `WARNING: undefined label: 'colors_def'`) - Drop support for Python 3.10 following [NEP-29](https://numpy.org/neps/nep-0029-deprecation_policy.html) - NumPy build system requirement no longer needs a python_version specification since the minimum supported Python version (now 3.10) supports NumPy >2. - Dropping support for 3.10 "conveniently" fixes consistent CI test failures on Ubuntu and Windows Python 3.10. 3. Fixes matplotlib docs builds that expected an internal matplotlib sphinx extension
4 participants
PR summary
When projects derive from our types, but don't override all the docstrings, they may want to use these extensions so that their docs build. Fixes #28234
However, this does mean that when enabled, you get
:mpltype:and:rc:roles added globally. I have not fully investigated it, but we may want to instead move to a Sphinx Domain. This would require changing the usage to something like:mpl:type:and:mpl:rc:. However, I do need to investigate how that will interact with intersphinx (as if it doesn't work, then we don't really help downstreams.)PR checklist