Improve the display for class attributes of params #4144
Conversation
|
|
||
| {% for item in attributes %} | ||
| .. autoproperty:: | ||
| .. autoattribute:: |
There was a problem hiding this comment.
It should be autoattribute, not autoproperty
There was a problem hiding this comment.
Currently, attributes are sorted alphabetically, which is not ideal.
I was able to get the attributes sorted alphabetically using https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#directive-option-autoclass-member-order by adding these lines at L7-8:
:members:
:member-order: bysource
Results in something like the below. Note how shade_offset comes before shade_fill
However, using :members: here means Figure and other classes are also affected, so not ideal. Might need to create a custom template separately for these class-based params?
There was a problem hiding this comment.
Might need to create a custom template separately for these class-based params?
Done in 3109877.
| >>> fig.show() | ||
| """ | ||
|
|
||
| #: Set clearances between the embellishment and the box border. It can be either a |
There was a problem hiding this comment.
It seems we should use the #: comment format to document attributes.
xref: https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#doc-comments-and-docstrings
There was a problem hiding this comment.
This is pretty cool, it also means we can get a permalink to the attributes like https://pygmt-dev--4144.org.readthedocs.build/en/4144/api/generated/pygmt.params.Box.html#pygmt.params.Box.clearance!
seisman
added
skip-changelog
|
Currently, attributes are sorted alphabetically, which is not ideal. |
|
/format |
seisman
force-pushed
the
fix/class-docstring
branch
from
0e1f50b to
3109877
Compare
seisman
changed the title
seisman
changed the title
There was a problem hiding this comment.
Just realized this is very similar to the doc/_templates/autosummary/enums.rst file added in #3693, except that there's the minigallery here. Not sure if it makes sense to combine them?
There was a problem hiding this comment.
Yes, but does a minigallery make sense for an Enum class?
There was a problem hiding this comment.
I can't seem to render the minigallery locally for some reason, so not sure how it looks like.
There was a problem hiding this comment.
Oh actually, it seems like the minigallery won't show up for Enums.
There was a problem hiding this comment.
Let's just keep the templates separate then. Feel free to go ahead and merge.
Fix #4138.
TODO:
BoxPatternPreview: