Skip to content

Improve the display for class attributes of params #4144

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

Merged
seisman merged 9 commits into from
Oct 9, 2025
Merged

Improve the display for class attributes of params #4144

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
13d48ed
Fix the display for docstrings of class attributes
seisman Oct 8, 2025
8851885
Add blank lines between attributes
seisman Oct 8, 2025
fe7f662
Fix pattern
seisman Oct 8, 2025
4d0f4f5
Merge branch 'main' into fix/class-docstring
seisman Oct 9, 2025
f6de91f
Also update docstrings of private classes
seisman Oct 9, 2025
6c537e9
Minor fix in pattern
seisman Oct 9, 2025
aca5631
Merge remote-tracking branch 'origin/fix/class-docstring' into fix/cl…
seisman Oct 9, 2025
58125e8
Minor fix in pattern
seisman Oct 9, 2025
3109877
Use a custom template for params
seisman Oct 9, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion doc/_templates/autosummary/class.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@
.. rubric:: Attributes

{% for item in attributes %}
.. autoproperty::
.. autoattribute::
Copy link
Member Author

@seisman seisman Oct 8, 2025

Choose a reason for hiding this comment

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

It should be autoattribute, not autoproperty

Copy link
Member

@weiji14 weiji14 Oct 9, 2025

Choose a reason for hiding this comment

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

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

image

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?

Copy link
Member Author

@seisman seisman Oct 9, 2025

Choose a reason for hiding this comment

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

Might need to create a custom template separately for these class-based params?

Done in 3109877.

{{ objname }}.{{ item }}
{% endfor %}
{% endif %}
Expand Down
46 changes: 19 additions & 27 deletions pygmt/params/box.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,33 +18,6 @@ class Box(BaseParam):
"""
Class for specifying the box around GMT embellishments.

Parameters
----------
clearance
Set clearances between the embellishment and the box border. It can be either a
scalar value or a sequence of two/four values.

- a scalar value means a uniform clearance in all four directions.
- a sequence of two values means separate clearances in x- and y-directions.
- a sequence of four values means separate clearances for left/right/bottom/top.
fill
Fill for the box [Default is no fill].
inner_gap
Gap between the outer and inner borders [Default is ``"2p"``].
inner_pen
Pen attributes for the inner border [Default to :gmt-term:`MAP_DEFAULT_PEN`].
pen
Pen attributes for the box outline.
radius
Draw a rounded rectangular border instead of sharp. Passing a value with unit
to control the corner radius [Default is ``"6p"``].
shade_offset
Place an offset background shaded region behind the box. A sequence of two
values (dx, dy) indicates the shift relative to the foreground frame [Default is
``("4p", "-4p")``].
shade_fill
Fill for the shaded region [Default is ``"gray50"``].

Examples
--------
>>> import pygmt
Expand All @@ -54,13 +27,32 @@ class Box(BaseParam):
>>> fig.show()
"""

#: Set clearances between the embellishment and the box border. It can be either a
Copy link
Member Author

@seisman seisman Oct 8, 2025

Choose a reason for hiding this comment

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

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

Copy link
Member

@weiji14 weiji14 Oct 8, 2025

Choose a reason for hiding this comment

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

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!

#: scalar value or a sequence of two/four values.
#:
#: - a scalar value means a uniform clearance in all four directions.
#: - a sequence of two values means separate clearances in x- and y-directions.
#: - a sequence of four values means separate clearances for left/right/bottom/top.
clearance: float | str | Sequence[float | str] | None = None

#: Fill for the box [Default is no fill].
fill: str | None = None

#: Gap between the outer and inner borders [Default is ``"2p"``].
inner_gap: float | str | None = None

#: Pen attributes for the inner border [Default to :gmt-term:`MAP_DEFAULT_PEN`].
inner_pen: str | None = None
#: Pen attributes for the box outline.
pen: str | None = None
#: Draw a rounded rectangular border instead of sharp. Passing a value with unit to
#: control the corner radius [Default is ``"6p"``].
radius: str | bool = False
#: Place an offset background shaded region behind the box. A sequence of two values
#: (dx, dy) indicates the shift relative to the foreground frame [Default is
#: ``("4p", "-4p")``].
shade_offset: Sequence[float | str] | None = None
#: Fill for the shaded region [Default is ``"gray50"``].
shade_fill: str | None = None

def _validate(self):
Expand Down
Loading