Skip to content

How to reproduce original GMT arguments in PyGMT documentation #631

Closed
#1182
Closed
How to reproduce original GMT arguments in PyGMT documentation#631
#1182
Assignees
maxrjones
Labels
documentationImprovements or additions to documentationhelp wantedHelping hands are appreciatedmaintenanceBoring but important stuff for the core devs
Milestone
0.4.0

Description

@weiji14
weiji14
opened on Sep 23, 2020

Description of the desired feature

The GMT documentation has many instances where bold and italicized fonts are mixed, looking something like:

+nargs

The PyGMT documentation has been rather inconsistent with this (see mentions at #525 (comment) and #620 (comment)).

What we should do is to standardize how we want +n args to be written in the documentation. This is a bit complicated, but boils down to (at least) two options:

  1. r" **+n**\ *args* ". Use a raw-string in Python, allowing us to follow upstream GMT (as per Complete documentation of grdimage #620 (comment))

  2. " **+n**\\ *args* ". Use a double-backslash to avoid the flake8 error W605 invalid escape sequence '\ '.

An alternative would be to find a way to ignore the flake8 error somehow for the ReST docstrings.

Also, should we find a way to put these in code-formatted blocks (i.e. with backticks), as mentioned at https://github.com/GenericMappingTools/pygmt/pull/525/files#r454746311?

Are you willing to help implement and maintain this feature? Somewhat short on time, but will look into it.

References:

Activity

  1. weiji14
    added
    documentationImprovements or additions to documentation
    on Sep 23, 2020

  2. seisman commented on Dec 17, 2020

    @seisman
    seisman
    on Dec 17, 2020
    Member

    This is what PEP-257 says:

    For consistency, always use """triple double quotes""" around docstrings. Use r"""raw triple double quotes""" if you use any backslashes in your docstrings. For Unicode docstrings, use u"""Unicode triple-quoted strings""".

    So, instead of using r" **+n**\ *args* " for each individual cases, we should use r for the whole docstring, e.g.,

    def function():
    r"""
    A long docstring string.

    We now can write doctsrings with backslashes **+n**\ *args*
    """

  3. seisman commented on Dec 18, 2020

    @seisman
    seisman
    on Dec 18, 2020
    Member

    As pointed out by @weiji14, the PyGMT documentation is inconsistently using italics, bold, and code strings.

    I think we can following these conventions:

    1. Use code for Python function parameters
    2. Use bold and italics for GMT syntax like +nargs, in which bold +n means it should be typed as it is, and italic args should be given a specific value.

    This is a good example of what it looks like (https://www.pygmt.org/dev/tutorials/frames.html):

    image

  4. seisman commented on Dec 18, 2020

    @seisman
    seisman
    on Dec 18, 2020
    Member

    Ping @GenericMappingTools/python @willschlitzer for thoughts on this.

  5. willschlitzer commented on Dec 19, 2020

    @willschlitzer
    willschlitzer
    on Dec 19, 2020
    Contributor

    @seisman I like this convention for explaining literal titles and the associated arguments that go with them. Are you thinking there should be similar formatting in the string of arguments given in the doctstring?

  6. seisman commented on Dec 19, 2020

    @seisman
    seisman
    on Dec 19, 2020
    Member

    Are you thinking there should be similar formatting in the string of arguments given in the doctstring?

    Yes, but need feedbacks first.

  7. seisman commented on Dec 22, 2020

    @seisman
    seisman
    on Dec 22, 2020
    Member

    Ping @GenericMappingTools/python for comments.

  8. seisman commented on Dec 29, 2020

    @seisman
    seisman
    on Dec 29, 2020
    Member

    Ping @GenericMappingTools/python, @GenericMappingTools/python-maintainers and @GenericMappingTools/python-contributors for thoughts on #631 (comment) and #631 (comment).

  9. weiji14 commented on Dec 29, 2020

    @weiji14
    weiji14
    on Dec 29, 2020
    MemberAuthor

    Let's go with Option 1 (using the raw string). Easier to copy from GMT, and avoids messy backslashes. Also agree on the backtick code blocks.

    Will need to document this (with an example) somewhere in CONTRIBUTING.md

  10. willschlitzer commented on Dec 29, 2020

    @willschlitzer
    willschlitzer
    on Dec 29, 2020
    Contributor

    I think making the entire docstring a raw string is the way to go; I think a double backslash might be confusing to some, and copying directly from GMT makes life easier.

    I can write this up in CONTRIBUTING.md when we come to a consensus.

  11. seisman commented on Dec 29, 2020

    @seisman
    seisman
    on Dec 29, 2020
    Member

    I can write this up in CONTRIBUTING.md when we come to a consensus.

    At least three of the maintainers agree with this. I think we can do it now.

  12. seisman commented on Dec 30, 2020

    @seisman
    seisman
    on Dec 30, 2020
    Member

    As most of us agree with the new docstring conventions, we should do:

    • document the docstring conventions
    • review the whole project and fix any inconsistency
  13. seisman
    added this to the 0.3.0 milestone on Dec 30, 2020
  14. seisman
    added
    good first issueGood for newcomers
    help wantedHelping hands are appreciated
    on Dec 30, 2020

  15. 9 remaining items

  16. seisman commented on Feb 12, 2021

    @seisman
    seisman
    on Feb 12, 2021
    Member

    @meghanrjones Please do! I'm planning on going through the documentation tomorrow; no complaints if you submit a PR for changes!

    Sounds good. I'll try to get it done before then.

    Great! Please try your best to follow the standards as documented here (https://github.com/GenericMappingTools/pygmt/blob/master/CONTRIBUTING.md#example-code-standards).

    There may be some cases that are not covered by the standards. We can discuss more later.

  17. seisman
    modified the milestones: 0.3.0, 0.4.0 on Feb 14, 2021
  18. weiji14
    added a commit that references this issue on Feb 14, 2021

    Update the docstrings in the plotting modules (#881)

    57da40a

  19. maxrjones commented on Feb 19, 2021

    @maxrjones
    maxrjones
    on Feb 19, 2021
    Member

    Is the convention for documenting defaults in PyGMT set? In GMT, it is typically brackets [ ] without any explanation before the default. I remember a comment in which @seisman mentioned that "[Default is ...]" is more clear than just "[...]", but I couldn't find that comment again.

  20. seisman commented on Feb 19, 2021

    @seisman
    seisman
    on Feb 19, 2021
    Member

    In GMT, it is typically brackets [ ] without any explanation before the default. I remember a comment in which @seisman mentioned that "[Default is ...]" is more clear than just "[...]",

    Yes, it's open for discussions. The GMT documentation sometimes also uses "[Default is ...]".

  21. maxrjones commented on Feb 20, 2021

    @maxrjones
    maxrjones
    on Feb 20, 2021
    Member

    Moving forward is seems that the GMT documentation will be going with "[Default is ...]" (see GenericMappingTools/gmt#4834).

  22. seisman
    added a commit that references this issue on Feb 22, 2021

    Update docstrings links for return classes (#954)

    c7736c1

  23. seisman commented on Mar 27, 2021

    @seisman
    seisman
    on Mar 27, 2021
    Member

    Moving forward is seems that the GMT documentation will be going with "[Default is ...]" (see GenericMappingTools/gmt#4834).

    I think we can document it in the "Example code standards" section, then close the issue, right?

  24. maxrjones commented on Mar 29, 2021

    @maxrjones
    maxrjones
    on Mar 29, 2021
    Member

    Moving forward is seems that the GMT documentation will be going with "[Default is ...]" (see GenericMappingTools/gmt#4834).

    I think we can document it in the "Example code standards" section, then close the issue, right?

    Yes, I can add that guideline after #1126 is merged.

  25. maxrjones
    self-assigned this
    on Mar 29, 2021
  26. seisman
    removed
    good first issueGood for newcomers
    on Apr 2, 2021
  27. seisman
    closed this as completedin #1182on Apr 5, 2021
  28. sixy6e
    added 2 commits that reference this issue on Dec 21, 2022

    Update the docstrings in the plotting modules (GenericMappingTools#881)

    c1137cc

    Update docstrings links for return classes (GenericMappingTools#954)

    c7ec319
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

documentationImprovements or additions to documentationhelp wantedHelping hands are appreciatedmaintenanceBoring but important stuff for the core devs

Type

No type

Projects

No projects

    Milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions