Improve PyGMT documentation #983

core-man · 2021-03-01T15:37:41Z

We have to decide whether we want to add quotes to all arguments, e.g., '05m' or 05m. Originally posted in #976 (comment).

We use quotes for many arguments, e.g.,

pygmt/pygmt/datasets/earth_relief.py

Lines 34 to 39 in afe9293

    
               resolution : str 
        
                   The grid resolution. The suffix ``d``, ``m`` and ``s`` stand for 
        
                   arc-degree, arc-minute and arc-second. It can be ``'01d'``, ``'30m'``, 
        
                   ``'20m'``, ``'15m'``, ``'10m'``, ``'06m'``, ``'05m'``, ``'04m'``, 
        
                   ``'03m'``, ``'02m'``, ``'01m'``, ``'30s'``, ``'15s'``, ``'03s'``, 
        
                   or ``'01s'``.

Meanwhile, we don't use quotes in some cases, e.g.,

pygmt/pygmt/datasets/earth_relief.py

Lines 44 to 45 in afe9293

    
                   Required for Earth relief grids with resolutions higher than 5 
        
                   arc-minute (i.e., ``05m``).

We could refer to other projects posted in #976 (comment)

Just checked other projects, numpy (https://numpy.org/doc/stable/reference/generated/numpy.datetime_as_string.html#numpy.datetime_as_string), pandas (https://pandas.pydata.org/docs/reference/api/pandas.read_csv.html) and matplotlib (https://matplotlib.org/stable/api/legend_api.html) use 'string', not 'string' .

The text was updated successfully, but these errors were encountered:

seisman · 2021-03-01T16:21:00Z

Also see #631

core-man · 2021-03-02T14:15:53Z

I feel I am totally new to the PyGMT documentation (https://www.pygmt.org/latest/). What I am feeling when I first go through the documentation may represent some new PyGMT users. I plan to go through the documentation from the landing page to the end and make some comments about what I feel in a PR/issue.

I quickly read the landing page, Overview, Installing, and Making your first figure. I have a few comments or confusion. Just take some for examples:

https://www.pygmt.org/latest/install.html#installing-gmt-and-other-dependencies: conda create --name pygmt python=3.9 pip numpy pandas xarray netcdf4 packaging gmt.
The pip suddenly appears. It is not in the dependence list or above.
https://www.pygmt.org/latest/install.html#using-pip
I know how to install latest development version from the link, but I don't know how to update the latest dev. I think it could be updated by running the same command again.
Do we have to add $ before Linux/macOS commands? For example, $ pip install pygmt.
https://www.pygmt.org/latest/install.html#finding-the-gmt-shared-library: "Sometimes, PyGMT will be unable to find the correct version of the GMT shared library."
Shall we indicate "GMT shared library" is libgmt here before we use it in the second paragraph.

@GenericMappingTools/python How do you think? or do you have any comments?

seisman · 2021-03-02T15:13:29Z

@core-man I think these are all good suggestions. We definitely need more new PyGMT users like you to help us find bugs in our documentation.

seisman · 2021-03-03T02:11:43Z

pygmt.org/latest/install.html#installing-gmt-and-other-dependencies: conda create --name pygmt python=3.9 pip numpy pandas xarray netcdf4 packaging gmt.
The pip suddenly appears. It is not in the dependence list or above.

pip is not a PyGMT dependence, but it's commonly used to install any other Python packages. I just tried conda create --name pygmt python, it installs the following packages, with pip included.

So I think it's OK to remove pip to avoid confusion.

The following packages will be downloaded:

    package                    |            build
    ---------------------------|-----------------
    certifi-2020.12.5          |   py39h6e9494a_1         143 KB  conda-forge
    python-3.9.2               |h2502468_0_cpython        12.5 MB  conda-forge
    python_abi-3.9             |           1_cp39           4 KB  conda-forge
    setuptools-49.6.0          |   py39h6e9494a_3         950 KB  conda-forge
    tzdata-2021a               |       he74cb21_0         121 KB  conda-forge
    ------------------------------------------------------------
                                           Total:        13.7 MB

The following NEW packages will be INSTALLED:

  ca-certificates    conda-forge/osx-64::ca-certificates-2020.12.5-h033912b_0
  certifi            conda-forge/osx-64::certifi-2020.12.5-py39h6e9494a_1
  libcxx             conda-forge/osx-64::libcxx-11.0.1-habf9029_0
  libffi             conda-forge/osx-64::libffi-3.3-h046ec9c_2
  ncurses            conda-forge/osx-64::ncurses-6.2-h2e338ed_4
  openssl            conda-forge/osx-64::openssl-1.1.1j-hbcf498f_0
  pip                conda-forge/noarch::pip-21.0.1-pyhd8ed1ab_0
  python             conda-forge/osx-64::python-3.9.2-h2502468_0_cpython
  python_abi         conda-forge/osx-64::python_abi-3.9-1_cp39
  readline           conda-forge/osx-64::readline-8.0-h0678c8f_2
  setuptools         conda-forge/osx-64::setuptools-49.6.0-py39h6e9494a_3
  sqlite             conda-forge/osx-64::sqlite-3.34.0-h17101e1_0
  tk                 conda-forge/osx-64::tk-8.6.10-h0419947_1
  tzdata             conda-forge/noarch::tzdata-2021a-he74cb21_0
  wheel              conda-forge/noarch::wheel-0.36.2-pyhd3deb0d_0
  xz                 conda-forge/osx-64::xz-5.2.5-haf1e3a3_1
  zlib               conda-forge/osx-64::zlib-1.2.11-h7795811_1010

2. pygmt.org/latest/install.html#using-pip
I know how to install latest development version from the link, but I don't know how to update the latest dev. I think it could be updated by running the same command again.

This is a good point. In the install guide, we show different ways to install PyGMT, but don't show any way to update it. I think we want people to use the latest PyGMT versions if possible, so we should add a subsection of "Upgrade PyGMT" or similar.

Do we have to add $ before Linux/macOS commands? For example, $ pip install pygmt.

Windows users may not know what the $ sign means. I think we have made it clear that some commands should be "run in a Python interpreter".

4. pygmt.org/latest/install.html#finding-the-gmt-shared-library: "Sometimes, PyGMT will be unable to find the correct version of the GMT shared library."
Shall we indicate "GMT shared library" is libgmt here before we use it in the second paragraph.

I think yes.

core-man · 2021-03-03T06:16:38Z

@weiji14 @seisman @willschlitzer shall I open a PR to submit some revisions directly so that you can review them in the PR instead of answering the comments here? I can still submit some comments to this issue if I've no idea about something and want your suggestions and answers.

seisman · 2021-03-03T06:27:11Z

Yes, please open a PR instead. It would be much easier to discuss.

core-man · 2021-03-03T07:28:32Z

On https://test.pypi.org/project/pygmt/, the title is pygmt 0.2.1. So the dev version name is a little different from the stable version? @GenericMappingTools/python-maintainers

seisman · 2021-03-03T15:20:18Z

On test.pypi.org/project/pygmt, the title is pygmt 0.2.1. So the dev version name is a little different from the stable version?

TestPyPI is only for testing purposes. We make a dev release for every commit merged in the master branch. The dev version string is like 0.3.1.dev52, in which 52 means 52 commits since the last stable release. On that page, it shows 0.2.1 simply because we made a v0.2.1 release when we tested how TestPyPI works. Obviously, TestPyPI shows the stable version instead of the pre-releases versions. I just deleted v0.2.1 from the TestPyPI to avoid confusion. Now it shows:

core-man · 2021-03-04T05:30:47Z

At https://www.pygmt.org/dev/index.html#documentation-for-other-versions,

Documentation for other versions

Development (reflects the master branch on GitHub)

Latest release

v0.3.0

v0.2.1

v0.2.0

The latest release is also 0.3.0, right? Why do we list both of them? How about merging them into one term?

Development (reflects the master branch on GitHub)

v0.3.0 (latest stable release)

v0.2.1

Same question for the left side-bar. Meanwhile, shall we move dev to be the first as the above list, or we can move the latest release to be the first in the above list?

Below is from GMT Documentation

https://www.generic-mapping-tools.org/documentation/

GMT 6.1.1 actually links to GMT 6.1, while Latest stable release links to GMT 6.1.1.

https://docs.generic-mapping-tools.org/latest/#

core-man · 2021-03-04T05:35:27Z

@GenericMappingTools/python I am still a little confused why we need the Quickstart subsection?
I think it is not for advanced Python users. But if it is for new Python users, shall we just recommend them to install PyGMT like Installing GMT and other dependencies and Installing PyGMT.

weiji14 · 2021-03-04T07:10:49Z

At https://www.pygmt.org/dev/index.html#documentation-for-other-versions,

Documentation for other versions

Development (reflects the master branch on GitHub)

Latest release

v0.3.0

v0.2.1

v0.2.0

The latest release is also 0.3.0, right? Why do we list both of them? How about merging them into one term?

Yes 0.3.0 is currently the latest, but the URL is different. One is a dynamic URL https://www.pygmt.org/latest which always resolves to the latest version, the other one is a static version URL https://www.pygmt.org/v0.3.0 useful as a permalink. E.g. I could go to https://www.pygmt.org/v0.1.0 and get the documentation for some old pygmt module.

@GenericMappingTools/python I am still a little confused why we need the Quickstart subsection?

The quickstart was added in v0.3.0 (#865), and is meant to be a one-liner installation step (because the conda pygmt package pulls in GMT/numpy/xarray/etc). I would actually recommend that beginners use this.

I think it is not for advanced Python users. But if it is for new Python users, shall we just recommend them to install PyGMT like Installing GMT and other dependencies and Installing PyGMT.

The steps below the Quickstart are basically the old install steps (see https://www.pygmt.org/v0.2.1/install.html), which break down the installation into several steps: Python/Numpy et al. --> GMT --> PyGMT. This is intended for more advanced people who may have a different Python and/or GMT setup (e.g. installing via an exe file).

core-man · 2021-03-04T07:57:07Z

@weiji14 Thanks for the detailed explanations. I see~

core-man · 2021-03-05T05:58:30Z

Currently, there is a note on almost every tutorial/gallery page:

Some pages miss it: Gallery, projection, subplots. Shall we add this note for these pages? By the way, how about making this note as a snippet so that we can simply include it for every tutorial and don't need to copy it. @GenericMappingTools/python

core-man · 2021-03-06T11:36:13Z

@GenericMappingTools/python If my understanding is right, +rincrement option in the tutorial for ISO code may mislead some new GMT users.

+r option in GMT DOC

Append +r to modify exact bounding box coordinates obtained from the polygon(s): Append inc, xinc/yinc, or winc/einc/sinc/ninc to adjust the final region boundaries to be multiples of these steps [default is no adjustment]. Alternatively, use +R to extend the region outward by adding these increments instead, or +e which is like +r but it ensures that the bounding box extends by at least 0.25 times the increment [no extension]. As an example, -RFR+r1 will select the national bounding box of France rounded to nearest integer degree.

Take JP as an example:

import pygmt
fig = pygmt.Figure()
fig.coast(
    region="JP",
    projection="M12c",
    land="lightgray",
)
print(fig.region)

Output:

[122.938515 145.820877  20.528774  45.523136]

Use [+r|R|e[incs]] option:

JP+R1: [121.938515 146.820877 19.528774 46.523136]
JP+R2: [120.938515 147.820877 18.528774 47.523136]
JP+R3: [119.938515 148.820877 17.528774 48.523136]
JP+r1: [122. 146. 20. 46.]
JP+r2: [122. 146. 20. 46.]
JP+r3: [120. 147. 18. 48.]
JP+e1: [122. 147. 20. 46.]
JP+e2: [122. 148. 20. 48.]
JP+e3: [120. 147. 18. 48.]

We can see:

+Rinc extends the region outward by adding these increments (using +R3, 119.938515 = 122.938515 - 3)
+rinc adjusts the final region boundaries to be multiples of these steps (using +r3, 120, 147, 18, 48 are multiples of 3)
+einc is similar to +rinc (final region boundaries to be multiples of these steps), but it ensures that the bounding box extends by at least 0.25 times the increment. So, +e1 adjusts 145.820877 to be 147 instead of 146 by +r1 since 146-145.820877=0.18 < 0.25*1. +e2 adjusts 145.820877 to be 148, 45.523136 to be 48 for the same reason.

I don't know if some statements in the user guide about this option are right or exact. For example,

Using +r rounds to the nearest increment.

Does the above statement mean to be multiples of these steps?

Expands the region setting outside the range of Japan by 3 degrees in all
directions
region="JP+r3",

The comment is a little misleading or wrong, since +r3 means the final region be multiples of 3.

The region increment can be appended with +e, which expands the bounding box by at least 25% beyond the increment.

Not exact? +e adjusts the final region boundaries to be multiples of these steps but ensures that the bounding box extends by at least 0.25 times the increment.

Expands the region setting outside the range of Japan by 3 degrees in all
directions, without rounding to the nearest increment.
region="JP+e3",

I cannot understand this comment which actually should be that for +R3.

core-man · 2021-03-06T15:34:47Z

Session.put_strings method is listed at https://www.pygmt.org/dev/api/generated/pygmt.clib.Session.html, but is not listed at https://www.pygmt.org/dev/api/index.html#gmt-c-api. So do we want to just ignore it at the second link?

seisman · 2021-03-06T17:33:20Z

Session.put_strings method is listed at pygmt.org/dev/api/generated/pygmt.clib.Session.html, but is not listed at pygmt.org/dev/api/index.html#gmt-c-api. So do we want to just ignore it at the second link?

Yes, @weiji14 found the issue in #975 (comment), and I added it in #975. But #975 won't be merged recently, so you can open a PR fixing it if you want.

core-man · 2021-03-06T18:03:04Z

Yes, @weiji14 found the issue in #975 (comment), and I added it in #975. But #975 won't be merged recently, so you can open a PR fixing it if you want.

Good to know. Waiting for that PR be merged.

maxrjones · 2021-03-24T17:19:08Z

Lots of great work here, @core-man! Are there any other PRs that you plan to submit as part of this issue or is it ready to be closed?

core-man · 2021-03-24T17:47:14Z

Lots of great work here, @core-man! Are there any other PRs that you plan to submit as part of this issue or is it ready to be closed?

@meghanrjones Thanks for the reminding. Actually, the initial topic at the top is not discussed and not resolved because I begin to work with you from this issue and go off-topic later. Which one shall we use, 'string', ``string``, or ``'string'``?

I think we may discuss here and fix them when a PR works on the file containing them in the future instead of finding and revising all of them in a PR. How do you think?

maxrjones · 2021-03-25T00:56:46Z

Even though it looks a bit silly in the source code and it’s different than pandas and other packages, I actually like how ``'string'`` gets rendered in the html docs. I haven't checked about how it looks in notebooks or other python environments - is that the main reason for changing to 'string'?

core-man · 2021-03-25T13:12:16Z

I think we have five ways to show a string value in the docstring. Please see the table below. (BTW, we can use either ' or " in the python source code to indicate a string value)

1: '	2: "	3: ' + `code`	4: " + `code`	5: `code` only

Some examples in PyGMT source codes are shown below:

'

pygmt/pygmt/src/which.py

Lines 34 to 35 in 955a55e

    
                   it. Use True or 'l' (default) to download to the current directory. Use 
        
                   'c' to place in the user cache directory or 'u' user data directory

"
This example shows double-quotes used in the python code. I don't find any example in the docstring.

pygmt/pygmt/datasets/earth_relief.py

Line 78 in 955a55e

>>> grid = load_earth_relief("30m", registration="gridline")

' + code

pygmt/pygmt/datasets/earth_relief.py

Line 36 in 955a55e

arc-degree, arc-minute and arc-second. It can be ``'01d'``, ``'30m'``,

This example sets a string value to a parameter.

pygmt/pygmt/src/plot.py

Line 85 in 955a55e

If plotting vectors (using ``style='V'`` or ``style='v'``), then

" + code (Most cases use it to set a string value to a parameter)

pygmt/pygmt/src/plot.py

Line 169 in 955a55e

``no_clip="c"`` to retain clipping but turn off plotting of

code only

pygmt/pygmt/datasets/earth_relief.py

Line 45 in 955a55e

arc-minute (i.e., ``05m``).

I think we may have two topics here:

A. Shall we add `` to highlight the string value?

When we only want to show the string value without its corresponding PyGMT parameter, I think we don't need to add the `` to highlight the string value. Sometimes it makes the documentation a little noisy.
When we set a string value to a PyGMT parameter, we could add the `` to highlight them. See the two examples in Points 3 and 4 above.

B. ' or "?

I feel both are okay.

maxrjones · 2021-03-25T16:57:36Z

Great summary! To start, want to open a PR adding your recommended documentation conventions for these two topics to the CONTRIBUTING.md example code standards section? People could recommend revisions to the guidance through a PR review if necessary - but these seem like a good starting point.

core-man · 2021-03-25T17:28:59Z

How about waiting for comments from other contributors and maintainers here for 1-2 days? Maybe they have better ideas.

maxrjones · 2021-03-25T17:37:04Z

How about waiting for comments from other contributors and maintainers here for 1-2 days? Maybe they have better ideas.

I thought that only people who would be aware of this conversation are those who have notifications turned on for every event in the PyGMT repo and the two others who have commented here (but on unrelated documentation topics), meaning that opening a PR would probably involve more people into the discussion without needing to open a separate, more focused issue. But, if you want to wait that is fine.

core-man · 2021-03-25T17:58:05Z

I thought that only people who would be aware of this conversation are those who have notifications turned on for every event in the PyGMT repo and the two others who have commented here (but on unrelated documentation topics), meaning that opening a PR would probably involve more people into the discussion without needing to open a separate, more focused issue.

Woow~ I see. Thanks a lot for the explanation 😄 . Let's open a PR.

maxrjones · 2021-03-25T18:01:17Z

I thought that only people who would be aware of this conversation are those who have notifications turned on for every event in the PyGMT repo and the two others who have commented here (but on unrelated documentation topics), meaning that opening a PR would probably involve more people into the discussion without needing to open a separate, more focused issue.

Woow~ I see.

I hope my comment did not come across as a rebuke and am very sorry if it did - there's definitely merits to both paths fowards.

core-man · 2021-03-25T18:05:52Z

Not at all, I think you are right. I thought all of us turn notifications on for every event. I am heading to bed now and will work on it tomorrow.

seisman · 2021-03-25T18:18:29Z

A. Shall we add `` to highlight the string value?

When we only want to show the string value without its corresponding PyGMT parameter, I think we don't need to add the `` to highlight the string value. Sometimes it makes the documentation a little noisy.

When we set a string value to a PyGMT parameter, we could add the `` to highlight them. See the two examples in Points 3 and 4 above.

B. ' or "?

I feel both are okay.

Single-quotes and double-quotes are the same in Python. Our codes use double quotes following the black code style. I think we should also use double quotes in docstrings.

Another alternative way is using bold text, for example, 05m, as bold text means literal arguments in both GMT and PyGMT documentation.

core-man added the bug Something isn't working label Mar 1, 2021

seisman added question Further information is requested and removed bug Something isn't working labels Mar 1, 2021

core-man changed the title ~~Have a consistent usage of quotes for all arguments~~ Improve PyGMT documentation Mar 3, 2021

core-man mentioned this issue Mar 3, 2021

Improve PyGMT documentation #996

Closed

5 tasks

This was referenced Mar 13, 2021

Tiny improvements for the line tyles gallery example #1053

Merged

Tiny improvement for the sampling along tracks gallery example #1054

Merged

core-man mentioned this issue Mar 26, 2021

Add more example code standards #1126

Merged

5 tasks

core-man self-assigned this Mar 26, 2021

seisman closed this as completed in #1126 Apr 4, 2021

seisman added this to the 0.4.0 milestone Apr 4, 2021

seisman added documentation Improvements or additions to documentation and removed question Further information is requested labels Apr 4, 2021

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Improve PyGMT documentation #983

Improve PyGMT documentation #983

core-man commented Mar 1, 2021 •

edited

Loading

seisman commented Mar 1, 2021

core-man commented Mar 2, 2021 •

edited

Loading

seisman commented Mar 2, 2021

seisman commented Mar 3, 2021

core-man commented Mar 3, 2021 •

edited

Loading

seisman commented Mar 3, 2021

core-man commented Mar 3, 2021 •

edited

Loading

seisman commented Mar 3, 2021

core-man commented Mar 4, 2021 •

edited

Loading

Documentation for other versions

core-man commented Mar 4, 2021

weiji14 commented Mar 4, 2021 •

edited

Loading

Documentation for other versions

core-man commented Mar 4, 2021

core-man commented Mar 5, 2021 •

edited

Loading

core-man commented Mar 6, 2021 •

edited

Loading

core-man commented Mar 6, 2021

seisman commented Mar 6, 2021 •

edited by weiji14

Loading

core-man commented Mar 6, 2021 •

edited by weiji14

Loading

maxrjones commented Mar 24, 2021

core-man commented Mar 24, 2021 •

edited

Loading

maxrjones commented Mar 25, 2021

core-man commented Mar 25, 2021 •

edited

Loading

maxrjones commented Mar 25, 2021

core-man commented Mar 25, 2021

maxrjones commented Mar 25, 2021

core-man commented Mar 25, 2021

maxrjones commented Mar 25, 2021

core-man commented Mar 25, 2021

seisman commented Mar 25, 2021

Improve PyGMT documentation #983

Improve PyGMT documentation #983

Comments

core-man commented Mar 1, 2021 • edited Loading

seisman commented Mar 1, 2021

core-man commented Mar 2, 2021 • edited Loading

seisman commented Mar 2, 2021

seisman commented Mar 3, 2021

core-man commented Mar 3, 2021 • edited Loading

seisman commented Mar 3, 2021

core-man commented Mar 3, 2021 • edited Loading

seisman commented Mar 3, 2021

core-man commented Mar 4, 2021 • edited Loading

Documentation for other versions

core-man commented Mar 4, 2021

weiji14 commented Mar 4, 2021 • edited Loading

Documentation for other versions

core-man commented Mar 4, 2021

core-man commented Mar 5, 2021 • edited Loading

core-man commented Mar 6, 2021 • edited Loading

core-man commented Mar 6, 2021

seisman commented Mar 6, 2021 • edited by weiji14 Loading

core-man commented Mar 6, 2021 • edited by weiji14 Loading

maxrjones commented Mar 24, 2021

core-man commented Mar 24, 2021 • edited Loading

maxrjones commented Mar 25, 2021

core-man commented Mar 25, 2021 • edited Loading

maxrjones commented Mar 25, 2021

core-man commented Mar 25, 2021

maxrjones commented Mar 25, 2021

core-man commented Mar 25, 2021

maxrjones commented Mar 25, 2021

core-man commented Mar 25, 2021

seisman commented Mar 25, 2021

core-man commented Mar 1, 2021 •

edited

Loading

core-man commented Mar 2, 2021 •

edited

Loading

core-man commented Mar 3, 2021 •

edited

Loading

core-man commented Mar 3, 2021 •

edited

Loading

core-man commented Mar 4, 2021 •

edited

Loading

weiji14 commented Mar 4, 2021 •

edited

Loading

core-man commented Mar 5, 2021 •

edited

Loading

core-man commented Mar 6, 2021 •

edited

Loading

seisman commented Mar 6, 2021 •

edited by weiji14

Loading

core-man commented Mar 6, 2021 •

edited by weiji14

Loading

core-man commented Mar 24, 2021 •

edited

Loading

core-man commented Mar 25, 2021 •

edited

Loading