Improve PyGMT documentation

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' .

Also see #631

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?

@core-man

@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.

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.

@weiji14

@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.

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

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

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:

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/#

@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.

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

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?

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'?

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.

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.

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

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.

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.

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.

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.

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.

Navigation Menu

Repository navigation

Improve PyGMT documentation #983

Documentation for other versions

Documentation for other versions

7 remaining items

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

	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'``.

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

	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

Improve PyGMT documentation #983

Description

Activity

seisman commented on Mar 1, 2021

core-man commented on Mar 2, 2021

seisman commented on Mar 2, 2021

seisman commented on Mar 3, 2021

core-man commented on Mar 3, 2021

seisman commented on Mar 3, 2021

core-man commented on Mar 3, 2021

seisman commented on Mar 3, 2021

core-man commented on Mar 4, 2021

Documentation for other versions

core-man commented on Mar 4, 2021

weiji14 commented on Mar 4, 2021

Documentation for other versions

7 remaining items

core-man commented on Mar 24, 2021

maxrjones commented on Mar 25, 2021

core-man commented on Mar 25, 2021

maxrjones commented on Mar 25, 2021

core-man commented on Mar 25, 2021

maxrjones commented on Mar 25, 2021

core-man commented on Mar 25, 2021

maxrjones commented on Mar 25, 2021

core-man commented on Mar 25, 2021

seisman commented on Mar 25, 2021

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions