Property tables #9461
Property tables #9461
Conversation
Note that the syntax used puts the ACCEPTS string in a rst comment, so they won't appear in the rendered docs. They need to be put higher than the Parameters table because numpydoc does not handle rst comments correctly...
2511a30 to
8cc0c57
Compare
| # these are not available for the object inspector until after the | ||
| # class is built so we define an initial set here for the init | ||
| # function and they will be overridden after object definition | ||
| docstring.interpd.update(Patch=""" |
There was a problem hiding this comment.
All looks good to me, but I'm not sure why these have been deleted?
There was a problem hiding this comment.
Because the proper version (with all the properties extracted from the docstrings) is defined at https://github.com/anntzer/matplotlib/blob/8cc0c57bc7dd638a503221f600f933efa671a046/lib/matplotlib/patches.py#L560, overwriting the old (& thus unused) definition. (Other cases are similar.)
lib/matplotlib/artist.py
Outdated
| ---------- | ||
| t : `~.Transform` | ||
|
|
||
| .. |
There was a problem hiding this comment.
This looks funny when rendered. Is that what was wanted? From your comment I assumed this wouldn't render...
There was a problem hiding this comment.
I had to put it before the table, or indented within it (actually that will probably look better). Fix coming...
(This is really a limitation of numpydoc.)
|
That renders better. I'm not clear on what this is supposed to do, however... Where do these "Accepts" now show up? Just in the code? Sorry for not following... |
6dc8c7a to
55708b9
Compare
|
Compare (for some reason the property table was not added to the Artist class itself, but it is inherited by subclasses). |
lib/matplotlib/artist.py
Outdated
| ---------- | ||
| snap : Optional[bool] | ||
| .. | ||
| ACCEPTS: Optional[bool] |
There was a problem hiding this comment.
This renders to this
Is it what you meant?
P.S: For me an optional argument is the one you can skip, so in that case .set_snap() should be valid, but here we have [ None | bool ]
There was a problem hiding this comment.
No, Optional[t] means Union[t, None] (https://docs.python.org/3/library/typing.html#typing.Optional).
Note that this is not the same concept as an optional argument, which is one that has a default. An optional argument with a default needn’t use the Optional qualifier on its type annotation (although it is inferred if the default is None). A mandatory argument may still have an Optional type if an explicit value of None is allowed.
There was a problem hiding this comment.
Well, that was confusing, thanks for clarifying.
There was a problem hiding this comment.
Actually I agree that foo or None is less confusing than Optional[None], fixed accordingly.
|
You have some funky error though: |
|
should be fixed |
55708b9 to
115b8e5
Compare
b7be07a to
dbd72b3
Compare
|
There seem to be a conflict, please backport manually |
|
@anntzer Hopefully I didn't mess up this merge, but the backport needs to be manually monkeyed with. |
Property tables Conflicts: lib/matplotlib/axes/_base.py - rejected documentation updates for behavior that was not backported lib/matplotlib/tests/test_artist.py - conflicts between added tests
|
backported to v2.1.x as 0f86067 |
As mentoned by @efiring in #9414 (comment), the "unknown" entries in the property tables are rather, hum, unsightly. Fix this by adding ACCEPTS entries to the relevant setters (or at least most of them). Also added a numpydoc Parameters table when appropriate.
I can't say I particularly like the approach, but it's what we have right now. The "dot dot" syntax puts the entry in a rst comment, so they won't appear in the rendered docs. I would also have preferred putting them after the numpydoc Parameters table, but numpydoc is apparently unaware that these are comments, and think that they are documentation for an argument named
...Also deleted some useless explicit renderings of the table (Text and Patch) -- these get overwritten after the corresponding artist class is fully defined.
PR Summary
PR Checklist