Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Fix doc references in subclasses of mpl._enum members #20174

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.

Sign up for GitHub

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

Jump to bottom
Closed
wants to merge 2 commits into from
Closed

Fix doc references in subclasses of mpl._enum members #20174

wants to merge 2 commits into from

Conversation

brunobeltran
Copy link
Contributor

@brunobeltran brunobeltran commented May 6, 2021 •
edited
Loading

Avoid using explicit references to private module in docs, instead let
intersphinx handle it.

PR Summary

numpydoc's xref breaks for external subclasses of Patch because we use references to .CapStyle and .JoinStyle (after importing those classes), but external library authors subclassing Patch are certainly not required to import them, so numpydoc cannot resolve the unqualified reference.

We do not wish to expose the full reference, matplotlib._enum.CapStyle (and similar for JoinStyle) in order to avoid tieing ourselves to this experimental/private module as much as possible.

Therefore, as mentioned here, this PR instead changes the references to the form CapStyle_ and JoinStyle_ to allow intersphinx to handle them.

Trying to add the full reference ~matplotlib._enums.CapStyle everywhere in the docstrings where it is relevant creates an absolute mess of docstring lines that are way too long in ways that can't be fixed. Since we're already using interpolation in most of the same places to list out the possible Join/CapStyles (%(JoinStyle)s expands to ('miter', 'round', 'bevel')), we add %(JoinStyleL)s that exands to ``~matplotlib._enums.JoinStyle``

This should fix #19839.

PR Checklist

  • [N/A] Has pytest style unit tests (and pytest passes).
  • Is Flake 8 compliant (run flake8 on changed files to check).
  • [N/A] New features are documented, with examples if plot related.
  • Documentation is sphinx and numpydoc compliant (the docs should build without error).
  • Conforms to Matplotlib style conventions (install flake8-docstrings and run flake8 --docstring-convention=all).
  • [N/A] New features have an entry in doc/users/next_whats_new/ (follow instructions in README.rst there).
  • [N/A] API changes documented in doc/api/next_api_changes/ (follow instructions in README.rst there).

@brunobeltran brunobeltran marked this pull request as draft May 6, 2021 18:37
@brunobeltran
Copy link
Contributor Author

First attempt threw warnings after passing locally, I'll mark as draft until it's passing.

@brunobeltran brunobeltran force-pushed the enum_docstring_fix branch from f2733d2 to bd5d341 Compare May 6, 2021 20:40
@brunobeltran
Copy link
Contributor Author

brunobeltran commented May 6, 2021 •
edited
Loading

Pretty sure the original strategy proposed (on a call during my post-graduation absence) of changing .CapStyle to CapStyle_ won't work because autodoc actually generates restructuredtext references of the form matplotlib._enum.CapStyle (as seen on the current build), so it would not actually hide it. Therefore I'm just going to drop the whole string in there. I don't think hiding the existence of the _enums module should be as high of a priority as fixing #19839.

@brunobeltran brunobeltran marked this pull request as ready for review May 6, 2021 20:45
@brunobeltran brunobeltran force-pushed the enum_docstring_fix branch from bd5d341 to 23457a1 Compare May 6, 2021 20:45
@brunobeltran
DOCS: fully qualify docstring _enum refs
c48dfad 
Avoid using explicit references to private module in docs, instead let
intersphinx handle it.
@brunobeltran brunobeltran force-pushed the enum_docstring_fix branch from 23457a1 to c48dfad Compare May 7, 2021 16:21
@brunobeltran
Copy link
Contributor Author

Test failure seems unrelated, restarting CI...

@jklymak
Copy link
Member

jklymak commented May 15, 2021

@brunobeltran how can we test this with other projects? Do you suggest merging and then just asking one of them to test their intersphinx?

@timhoffm
Copy link
Member

timhoffm commented May 18, 2021 •
edited
Loading

Pretty sure the original strategy proposed (on a call during my post-graduation absence) of changing .CapStyle to CapStyle_ won't work because autodoc actually generates restructuredtext references of the form matplotlib._enum.CapStyle (as seen on the current build), so it would not actually hide it.

I'm not sure I'm following. Wasn't there the idea using ReST labels and references.

cs : :ref:`CapStyle` or %(CapStyle)s

and

.. _CapStyle:

.. autoclass:: CapStyle
      :members: demo
      :exclude-members: butt, round, projecting, input_description

so that we're not dependent on name resolution at all?

@jklymak jklymak added the status: needs clarification Issues that need more information to resolve. label May 21, 2021
@jklymak jklymak marked this pull request as draft May 21, 2021 20:20
@jklymak
Copy link
Member

jklymak commented Oct 8, 2023

I'm not sure the original issue is still an issue, so I'll close this, but feel free to request a re-open.

@jklymak jklymak closed this Oct 8, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers
No reviews
Assignees
No one assigned
Labels
status: needs clarification Issues that need more information to resolve.
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.

Subclasses of Polygon with numpydoc xref throws error b/c of CapStyle, JoinStyle
4 participants
@brunobeltran @jklymak @timhoffm @oscargus