Skip to content

Better way to document the aliases in docstrings #4011

@seisman

Description

@seisman

In the initial version of the alias system, each GMT option flag is aliased to a single parameter PyGMT, so documenting the aliases in docstrings is simple and can be fully automatic. The aliases docstrings are like:

**Aliases:**

- J=projection
- B=frame
- R=region

Then we realized that sometimes an option flag is too complicated and should be aliased to multiple parameters, and they're documented like below since #3965:

**Aliases:**

- J=projection
- B=frame
- R=region
- A=constantfill/gridfill/neighborfill/splinefill

With the new alias system introduced in #4000, we have to manually maintain the aliases in docstrings.

We need to discuss what the docstrings look like, especially for option flags that are aliased to multiple parameters. Let me take -U as an example. The GMT CLI syntax is -U[label][+jjustify][+odx[/dy]][+ttext], then the docstrings can be:

U=label, justify (+j), offset (+o), text (+t)

or

U=label, +j: justify, +o: offset, +t: text

We also need to add a documentation explaining how the new alias system works and how to read and understand the aliases in docstrings.

Originally posted by @seisman in #4000 (comment)

Metadata

Metadata

Assignees

No one assigned

    Labels

    discussionsNeed more discussion before taking further actions

    Type

    No type

    Projects

    No projects

    Milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions