Improve the display for class attributes of params (#4144)

Author: seisman

doc/_templates/autosummary/class.rst

@@ -8,7 +8,7 @@
 .. rubric:: Attributes
 
 {% for item in attributes %}
-.. autoproperty::
+.. autoattribute::
     {{ objname }}.{{ item }}
 {% endfor %}
 {% endif %}

doc/_templates/autosummary/params.rst

@@ -0,0 +1,14 @@
+{{ fullname | escape | underline }}
+
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ objname }}
+    :members:
+    :member-order: bysource
+
+.. minigallery:: {{ fullname }}
+    :add-heading:
+
+.. raw:: html
+
+     <div style='clear:both'></div>

doc/api/index.rst

@@ -210,6 +210,7 @@ Class-style Parameters
 
 .. autosummary::
     :toctree: generated
+    :template: autosummary/params.rst
 
     Box
     Pattern

pygmt/datasets/load_remote_dataset.py

@@ -17,49 +17,41 @@
 class Resolution(NamedTuple):
     """
     Resolution code, the available grid registrations and whether it is tiled.
-
-    Attributes
-    ----------
-    code
-        The resolution code. E.g., "01d", "30m", "01s".
-    registrations
-        A list of the accepted registrations for a given resolution. Can be either
-        "pixel" or "gridline".
-    tiled
-        States if the grid is tiled, which requires an argument for ``region``.
     """
 
+    #: The resolution code. E.g., "01d", "30m", "01s".
     code: str
+
+    #: A list of the accepted registrations for a given resolution. Can be either
+    #: "pixel" or "gridline".
     registrations: Sequence[str] = ["gridline", "pixel"]
+
+    #: States if the grid is tiled, which requires an argument for ``region``.
     tiled: bool = False
 
 
 class GMTRemoteDataset(NamedTuple):
     """
     Standard information about a dataset and grid metadata.
-
-    Attributes
-    ----------
-    description
-        The name assigned as an attribute to the DataArray.
-    kind
-        The kind of the dataset source. Valid values are ``"grid"`` and ``"image"``.
-    units
-        The units of the values in the DataArray.
-    resolutions
-        Dictionary of available resolution as keys and Resolution objects as values.
-    extra_attributes
-        A dictionary of extra or unique attributes of the dataset.
-    crs
-        The coordinate reference system of the raster image. Need to be set for images,
-        and should be ``None`` for grids.
     """
 
+    #: The name assigned as an attribute to the DataArray.
     description: str
+
+    #: The kind of the dataset source. Valid values are ``"grid"`` and ``"image"``.
     kind: Literal["grid", "image"]
+
+    #: The units of the values in the DataArray.
     units: str | None
+
+    #: Dictionary of available resolution as keys and Resolution objects as values.
     resolutions: Mapping[str, Resolution]
+
+    #: A dictionary of extra or unique attributes of the dataset.
     extra_attributes: Mapping[str, Any]
+
+    #: The coordinate reference system of the raster image. Need to be set for images,
+    #: and should be ``None`` for grids.
     crs: str | None = None
 
 

pygmt/datasets/samples.py

@@ -209,16 +209,11 @@ def _load_earth_relief_holes() -> xr.DataArray:
 class GMTSampleData(NamedTuple):
     """
     Information of a sample dataset.
-
-    Attributes
-    ----------
-    func : callable
-        The function that loads the sample dataset.
-    description : str
-        The description of the sample dataset.
     """
 
+    #: The function that loads the sample dataset.
     func: Callable
+    #: The description of the sample dataset.
     description: str
 
 

pygmt/params/box.py

@@ -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
@@ -54,13 +27,36 @@ class Box(BaseParam):
     >>> fig.show()
     """
 
+    #: 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.
     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):

pygmt/params/pattern.py

@@ -31,26 +31,6 @@ class Pattern(BaseParam):
        :width: 75%
        :align: center
 
-    Parameters
-    ----------
-    pattern
-        The pattern to use. It can be specified in two forms:
-
-        - An integer in the range of 1-90, corresponding to one of 90 predefined 64x64
-          bit-patterns. [Default is 1].
-        - Name of a 1-, 8-, or 24-bit image raster file, to create customized, repeating
-          images using image raster files.
-    dpi
-        Resolution of the pattern in dots per inch (DPI) [Default is 300].
-    bgcolor/fgcolor
-        The background/foreground color for predefined bit-patterns or 1-bit images.
-        Setting either to an empty string will yield a transparent background/foreground
-        where only the foreground/background pixels will be painted. [Default is white
-        for background and black for foreground].
-    invert
-        If ``True``, the pattern will be bit-inverted, i.e., white and black areas will
-        be interchanged (only applies to predefined bit-patterns or 1-bit images).
-
     Examples
     --------
     Draw a global map with land areas filled with pattern 15 in a light red background
@@ -69,10 +49,28 @@ class Pattern(BaseParam):
     >>> fig.show()
     """
 
+    #: The pattern to use. It can be specified in two forms:
+    #:
+    #: - An integer in the range of 1-90, corresponding to one of 90 predefined 64x64
+    #:   bit-patterns. [Default is 1].
+    #: - Name of a 1-, 8-, or 24-bit image raster file, to create customized, repeating
+    #:   images using image raster files.
     pattern: int | PathLike = 1
+
+    #: Resolution of the pattern in dots per inch (DPI) [Default is 300].
     dpi: int | None = None
+
+    #: The background color for predefined bit-patterns or 1-bit images.
+    #: Setting either ``bgcolor`` or ``fgcolor`` to an empty string will yield a
+    #: transparent background/foreground where only the foreground/background pixels
+    #: will be painted. [Default is white for background and black for foreground].
     bgcolor: str | None = None
+
+    #: The foreground color for predefined bit-patterns or 1-bit images.
     fgcolor: str | None = None
+
+    #: If ``True``, the pattern will be bit-inverted, i.e., white and black areas will
+    #: be interchanged (only applies to predefined bit-patterns or 1-bit images).
     invert: bool = False
 
     def _validate(self):