List existing rcParams in rcParams docstring. #18440
Conversation
This is useful for those who mostly live at the command line, letting one see the list of rcParams with `pydoc matplotlib.rcParams` (for example). Making `Substitution` always perform docstring dedenting simplifies the implementation here; I'm not sure you'd ever\* want to do an un-dedented interpolation anyways... (\*for certain values of "ever") Fix colorbar docstrings indentation accordingly.
|
|
||
| def dedent_interpd(func): | ||
| """Dedent *func*'s docstring, then interpolate it with ``interpd``.""" | ||
| func.__doc__ = inspect.getdoc(func) |
There was a problem hiding this comment.
Changing getdoc to cleandoc doesn't have an effect?
There was a problem hiding this comment.
one is called on the function, the other on the docstring?
There was a problem hiding this comment.
getdoc says: "If the documentation string for an object is not provided and the object is a class, a method, a property or a descriptor, retrieve the documentation string from the inheritance hierarchy."
This inheritance doesn't apply to func.__doc__, no?
There was a problem hiding this comment.
Ah indeed. On the other hand this was accidentally changed in the other direction in https://github.com/matplotlib/matplotlib/pull/13125/files#diff-0b973b83a5020c0418842e20e3ffc56cR115 so I guess I can always argue it's just going back to the old behavior :)
There was a problem hiding this comment.
Something broke doc build though, though I'm not sure if it was this change specifically.
There was a problem hiding this comment.
oops, had a fix but forgot to push it
There was a problem hiding this comment.
AFAICT, I could not find any dedent_interpd on things that didn't have their own docstring.
There was a problem hiding this comment.
+0.9. I'm a bit worried (as usual) that some people are using this stuff for their docs, and this would be an API change. OTOH it's only affecting docstrings. The worst that can happen are badly indented plain text docs (could happen on user code) and bad .rst code (not so much of an issue because people could fix this before punishing their release. So nothing really bad can happen without deprecation.
We don't need dedent_interpd anymore. This should get a deprecation. It cannot be deleted directly. If some lib was using that function, removing it would break the import.
|
If you prefer I can set up the usual boilerplate to not modify the public API but instead use some private machinery to achieve the same effect (well, I guess the whole |
|
|
||
| def dedent_interpd(func): | ||
| """Dedent *func*'s docstring, then interpolate it with ``interpd``.""" | ||
| func.__doc__ = inspect.getdoc(func) |
There was a problem hiding this comment.
AFAICT, I could not find any dedent_interpd on things that didn't have their own docstring.
matplotlib#18440 removed the dedent_intepd function and replaced it with a `Substitution` instance. API-wise this is transparent, but we cannot reference `detent_interpd` in Sphinx docs any more. This PR changes the only reference to a literal.
matplotlib#18440 removed the dedent_intepd function and replaced it with a `Substitution` instance. API-wise this is transparent, but we cannot reference `detent_interpd` in Sphinx docs any more. This PR changes the only reference to a literal.
Fix doc build failure due to #18440
This is useful for those who mostly live at the command line, letting
one see the list of rcParams with
pydoc matplotlib.rcParams(forexample).
Making
Substitutionalways perform docstring dedenting simplifies theimplementation here; I'm not sure you'd ever* want to do an un-dedented
interpolation anyways... (*for certain values of "ever") Fix colorbar
docstrings indentation accordingly.
On the other hand I'm not particularly wedded to the format of the item
list either.
PR Summary
PR Checklist
pytestpasses).flake8on changed files to check).flake8-docstringsandpydocstyle<4and runflake8 --docstring-convention=all).doc/users/next_whats_new/(follow instructions in README.rst there).doc/api/next_api_changes/(follow instructions in README.rst there).