Skip to content

fmt_docstring: Split common docstrings into COMMON_PARAMETERS and COMMON_DOCSTRINGS #4918

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 2 commits into from
Sep 28, 2026
Merged

fmt_docstring: Split common docstrings into COMMON_PARAMETERS and COMMON_DOCSTRINGS #4918

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
c4dfe4a
fmt_docstring: Split common docstrings into COMMON_PARAMETERS and COM…
seisman Sep 24, 2026
033aa91
Merge branch 'main' into refactor/common_docstrings
seisman Sep 28, 2026
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
4 changes: 2 additions & 2 deletions doc/contributing.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -578,14 +578,14 @@ After the initial implementation, missing aliases can be added in separate PRs:
* Select a suitable alias for each GMT option, following the guidelines in the
[code style](#code-style) section. Before creating a new alias, check:

- whether the parameter is listed in the `COMMON_DOCSTRINGS` dictionary in
- whether the parameter is listed in the `COMMON_PARAMETERS` dictionary in
`pygmt/helpers/decorators.py`
- whether other wrapped GMT modules have a similar parameter
- whether [GMT.jl](https://www.generic-mapping-tools.org/GMTjl_doc/) has defined an alias
* Add the alias to the `AliasSystem` class and the function signature.
* Add the alias and description to the parameters section of the docstring, using the
`fmt_docstring` decorator to add descriptions for parameters included in the
`COMMON_DOCSTRINGS` dictionary.
`COMMON_PARAMETERS` dictionary.

### Testing your Code

Expand Down
20 changes: 12 additions & 8 deletions pygmt/helpers/decorators.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@
from pygmt.exceptions import GMTParameterError, GMTValueError
from pygmt.helpers.utils import is_nonstr_iter

COMMON_DOCSTRINGS = {
COMMON_PARAMETERS = {
"area_thresh": r"""
area_thresh
*min_area*\ [/*min_level*/*max_level*][**+a**\[**g**\|\ **i**]\
Expand Down Expand Up @@ -383,6 +383,15 @@
Full documentation is at :gmt-docs:`gmt.html#w-full`.""",
}

COMMON_DOCSTRINGS = {
"table_classes": (
":class:`numpy.ndarray`, a :class:`pandas.DataFrame`, an\n"
" :class:`xarray.Dataset` made up of 1-D :class:`xarray.DataArray`\n"
" data variables, or a :class:`geopandas.GeoDataFrame` containing the\n"
" tabular data"
Comment on lines +388 to +391

@yvonnefroehlich yvonnefroehlich Sep 28, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Are these leading white spaces are needed?

Suggested change
":class:`numpy.ndarray`, a :class:`pandas.DataFrame`, an\n"
" :class:`xarray.Dataset` made up of 1-D :class:`xarray.DataArray`\n"
" data variables, or a :class:`geopandas.GeoDataFrame` containing the\n"
" tabular data"
":class:`numpy.ndarray`, a :class:`pandas.DataFrame`, an \n"
":class:`xarray.Dataset` made up of 1-D :class:`xarray.DataArray` \n"
"data variables, or a :class:`geopandas.GeoDataFrame` containing the \n"
"tabular data"

@seisman seisman Sep 28, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

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

Yes, these whitespaces are needed. The text string is directly inserted into the docstring. If removing these whitespaces, we will see docstrings like:

data
    Pass in either a file name to an ASCII data table, a 1-D/2-D 
    :class:`numpy.ndarray`, a :class:`pandas.DataFrame`, an
:class:`numpy.ndarray`, a :class:`pandas.DataFrame`, an
data variables, or a :class:`geopandas.GeoDataFrame` containing the
tabular data

I plan to make it more intuitive in a later PR.

),
}


def fmt_docstring(module_func):
r"""
Expand Down Expand Up @@ -465,14 +474,9 @@ def fmt_docstring(module_func):
aliases.append(f" - {arg} = {alias}")
filler_text["aliases"] = "\n".join(aliases)

filler_text["table_classes"] = (
":class:`numpy.ndarray`, a :class:`pandas.DataFrame`, an\n"
" :class:`xarray.Dataset` made up of 1-D :class:`xarray.DataArray`\n"
" data variables, or a :class:`geopandas.GeoDataFrame` containing the\n"
" tabular data"
)
filler_text.update(COMMON_DOCSTRINGS)

for marker, text in COMMON_DOCSTRINGS.items():
for marker, text in COMMON_PARAMETERS.items():
# Remove the indentation and the first line break from the multiline
# strings so that it doesn't mess up the original docstring
filler_text[marker] = textwrap.dedent(text.lstrip("\n"))
Expand Down
Loading