Improve PyGMT documentation

[core-man]

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

[seisman]

Also see #631

[core-man]

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]

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

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

3. 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]

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

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

[core-man]

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]

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]

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]

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