Fix missing artist property reference for _CollectionWithSizes.set_sizes #29560
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Child classes of `_CollectionWithSizes` that list all their properties via "%(MyClass:kwdoc)s" want to reference `_CollectionWithSizes.set_sizes`, but that is not documented because `_CollectionWithSizes` is not documented. Since all the child classes are documented with the option `:inherited-members:`, the child classes all explicitly document `set_sizes` themselves. This PR changes the link target to that. Note: One could consider documenting `_CollectionWithSizes` explicitly or even making it public. But these are larger decisions that I don't want to go into now, because that means reconsidering using the `:inherited-members:` for Collections documentation or even compatibility concerns when making it public. The fix here is well contained and can be reverted or adapted as needed in the future. It's an important fix because it removes `set_sizes` from `missing-references.json`. The docstring line numbers that are hard-coded in there can change due to introduction of new properties or changes in the docstring above the "%(MyClass:kwdoc)s" placeholder, which has repeatedly lead to doc failures - latest affected PR is matplotlib#29044 - and is really annoying. there
This was referenced Feb 1, 2025
timhoffm
added a commit
to timhoffm/matplotlib
that referenced
this pull request
Feb 1, 2025
This is needed to get `_CollectionWithSizes.set_sizes` documented so that it can be referenced. Alternative approach to matplotlib#29560.
|
Does not completely as intended. Not all child classes are generated with :inherited-members. These are not covered and fail: They fail because they are sub-subclasses that do use :inherited-members:. One could try to find the right level to link to, but I will first try whether a minimal documentation of |
timhoffm
added a commit
to timhoffm/matplotlib
that referenced
this pull request
Feb 1, 2025
This is needed to get `_CollectionWithSizes.set_sizes` documented so that it can be referenced. Alternative approach to matplotlib#29560.
timhoffm
added a commit
to timhoffm/matplotlib
that referenced
this pull request
Feb 1, 2025
This is needed to get `_CollectionWithSizes.set_sizes` documented so that it can be referenced. Alternative approach to matplotlib#29560.
timhoffm
added a commit
to timhoffm/matplotlib
that referenced
this pull request
Feb 1, 2025
This is needed to get `_CollectionWithSizes.set_sizes` documented so that it can be referenced. Alternative approach to matplotlib#29560.
timhoffm
added a commit
to timhoffm/matplotlib
that referenced
this pull request
Feb 1, 2025
This is needed to get `_CollectionWithSizes.set_sizes` documented so that it can be referenced. Alternative approach to matplotlib#29560.
|
Closing in favor of #29561 |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Child classes of
_CollectionWithSizesthat list all their properties via "%(MyClass:kwdoc)s" want to reference_CollectionWithSizes.set_sizes, but that is not documented because_CollectionWithSizesis not documented.Since all the child classes are documented with the option
:inherited-members:, the child classes all explicitly documentset_sizesthemselves. This PR changes the link target to that.This fixes the broken link in all docstrings that list the possible kwarg values for collections such as in https://matplotlib.org/devdocs/api/_as_gen/matplotlib.axes.Axes.broken_barh.html:
It also removes the need for
_CollectionWithSizes.set_sizesentries inmissing-references.json. This is important because the docstring line numbers that are hard-coded in there can change due to introduction of new properties or changes in the docstring above the "%(MyClass:kwdoc)s" placeholder, which has repeatedly lead to doc failures - latest affected PR is #29044 - and is really annoying.Note: One could alternatively consider documenting
_CollectionWithSizesexplicitly or even making it public. But these are larger decisions that I don't want to go into now, because that means reconsidering using the:inherited-members:for Collections documentation or even compatibility concerns when making it public.The fix here is well contained and can be reverted or adapted as needed in the future.