Skip to content

Add a note to pyplot docstrings referencing the corresponding object methods #27909

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Mar 20, 2024

Conversation

timhoffm
Copy link
Member

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.

@github-actions github-actions bot added topic: pyplot API Documentation: user guide files in galleries/users_explain or doc/users labels Mar 11, 2024
``__qualname__`` is e.g. only "table" and not "Axes.table". This
function fixes that.

Note that the function itself is patched, so that
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Alternatively, since you've wrapped all of them with this function, you could return a new function from here and not modify the original.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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}"
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do you know examples of each type (Notes/no Notes/no Refs/etc) that we could check here?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For the four branch aternative to detect the insert position:
NOTES: margins
REFERENCES: cohere
SEE ALSO: hlines
NONE: title

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Per https://numpydoc.readthedocs.io/en/latest/format.html "See Also" should come before "Notes" and we also have to check for "Examples"?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

but it looks like its rendering in the correct order in hlines so I am confused...

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

image

@timhoffm timhoffm force-pushed the doc-pyplot-ref branch 4 times, most recently from 43311a1 to d6033d1 Compare March 14, 2024 10:10
@tacaswell tacaswell added this to the v3.9.0 milestone Mar 14, 2024
tacaswell
tacaswell previously approved these changes Mar 14, 2024
@tacaswell tacaswell dismissed their stale review March 14, 2024 15:54

We should get the order correct

@tacaswell
Copy link
Member

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 timhoffm marked this pull request as draft March 14, 2024 16:24
@timhoffm
Copy link
Member Author

Yes, I mixed up the sectioning. Fixed.

@timhoffm timhoffm marked this pull request as ready for review March 14, 2024 22:42
methods

Partial fix for matplotlib#17786: This adds notes for the pyplot functions
auto-generated by boilerplate.py.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Documentation: user guide files in galleries/users_explain or doc/users topic: pyplot API
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants