Skip to content

Only document the long-form arguments #473

Closed

Description

@seisman

Description of the problem

GMT command line and its C API only accept single-character arguments, e.g., -B and -J, whereas Python and PyGMT users mostly would prefer long-form arguments instead, e.g., frame for -B, projection for -J. Currently, PyGMT supports both single-character and long-form arguments, but we definitely will disallow single-character arguments in the future. See issue #262 for the reasons.

Currently, the documentation is pretty confusing. Take the documentation of Figure.coast() as an example. Below is what it looks like now:
image

For PyGMT users who never used GMT before, it's not clear what the aliases mean. I believe most of them are confused about the inconsistency of the single-character arguments in the coast documentation and the long-form arguments in the tutorials and gallery.

It will be a lot of work to fully implement #262, but at least now we should stop documenting single-character arguments and document long-form arguments instead.

What we can do:

  • Replace all single-character arguments with the corresponding long-form arguments, e.g., B->frame, J->projection.
  • Remove the aliases from the docstring

Activity

  1. weiji14 commented on Jun 1, 2020

    @weiji14
    Member

    A quick way to catch most of these is by fixing the common aliases (e.g. R=region, J=projection) listed in https://github.com/GenericMappingTools/pygmt/blob/master/pygmt/helpers/decorators.py. Should add a few others as well (e.g. l=label for legend, and c=axes for subplot once #412 is sorted). We can then slowly handle all of the other edge cases.

    Edit: I've removed most of the short-aliases (except R, J, B, CPT, G, W, U) for plotin the plot3d PR (since they were basically the same), will be visible once #471 is merged in, preview at https://pygmt-git-mapping-plot3d.gmt.now.sh/api/generated/pygmt.Figure.plot.html#pygmt.Figure.plot.

  2. added this to the 0.1.x milestone on Jun 29, 2020
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentationgood first issueGood for newcomershelp wantedHelping hands are appreciated

    Type

    No type

    Projects

    No projects

      Milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions