Add a note to pyplot docstrings referencing the corresponding object methods#27909
Add a note to pyplot docstrings referencing the corresponding object methods#27909QuLogic merged 2 commits intomatplotlib:mainfrom
Conversation
github-actions
bot
added
topic: pyplot API
Documentation: user guide
timhoffm
force-pushed
the
doc-pyplot-ref
branch
from
e2b7ae2 to
7c84e1f
Compare
| ``__qualname__`` is e.g. only "table" and not "Axes.table". This | ||
| function fixes that. | ||
|
|
||
| Note that the function itself is patched, so that |
There was a problem hiding this comment.
Alternatively, since you've wrapped all of them with this function, you could return a new function from here and not modify the original.
There was a problem hiding this comment.
For the scope of this PR, I don't care too much how this is implemented, I just need a correct __qualname__ and changing is good enough.
Yes, you could create a new function, but that's an additional indirection. While negligible from a performance perspective, it shows up e.g. in stacktraces. I'm not even sure that this way of adding functionality to classes reasonable style and what other edge-case consequences that has. Alternatively, one could make the original functions private. But that's all for a different PR.
| before = doc + "\n" | ||
| after = "" | ||
|
|
||
| func.__doc__ = f"{before}\nNotes\n-----\n\n.. note::\n\n {message}\n{after}" |
There was a problem hiding this comment.
Do you know examples of each type (Notes/no Notes/no Refs/etc) that we could check here?
There was a problem hiding this comment.
For the four branch aternative to detect the insert position:
NOTES: margins
REFERENCES: cohere
SEE ALSO: hlines
NONE: title
There was a problem hiding this comment.
Per https://numpydoc.readthedocs.io/en/latest/format.html "See Also" should come before "Notes" and we also have to check for "Examples"?
There was a problem hiding this comment.
but it looks like its rendering in the correct order in hlines so I am confused...
There was a problem hiding this comment.
It looks like something in the html pipeline is fixing the order as
In [2]: print(plt.hlines.__doc__)
Plot horizontal lines at each *y* from *xmin* to *xmax*.
Parameters
----------
y : float or array-like
y-indexes where to plot the lines.
xmin, xmax : float or array-like
Respective beginning and end of each line. If scalars are
provided, all lines will have the same length.
colors : :mpltype:`color` or list of color , default: :rc:`lines.color`
linestyles : {'solid', 'dashed', 'dashdot', 'dotted'}, default: 'solid'
label : str, default: ''
Returns
-------
`~matplotlib.collections.LineCollection`
Other Parameters
----------------
data : indexable object, optional
If given, the following parameters also accept a string ``s``, which is
interpreted as ``data[s]`` (unless this raises an exception):
*y*, *xmin*, *xmax*, *colors*
**kwargs : `~matplotlib.collections.LineCollection` properties.
Notes
-----
.. note::
This is the :ref:`pyplot wrapper <pyplot_interface>` for `.axes.Axes.hlines`.
See Also
--------
vlines : vertical lines
axhline : horizontal line across the Axes
but
timhoffm
force-pushed
the
doc-pyplot-ref
branch
4 times, most recently
from
43311a1 to
d6033d1
Compare
|
I think we should be checking for Examples and References and do not need to special case See Also. I won't block merging over this, but felt I should take back my approval. |
timhoffm
force-pushed
the
doc-pyplot-ref
branch
from
d6033d1 to
5c8a7d0
Compare
|
Yes, I mixed up the sectioning. Fixed. |
timhoffm
force-pushed
the
doc-pyplot-ref
branch
from
5c8a7d0 to
9d1c42d
Compare
methods Partial fix for matplotlib#17786: This adds notes for the pyplot functions auto-generated by boilerplate.py.
timhoffm
force-pushed
the
doc-pyplot-ref
branch
from
9d1c42d to
2cdd078
Compare
3 participants
Partial fix for #17786: This adds notes for the pyplot functions auto-generated by boilerplate.py.
As a prerequisite, this includes a first commit fixing the
__qualname__of Axes methods that are defined as functions in other modules and only added as attributes to Axes.