Add instructions to upgrade installed PyGMT version

[core-man]

Description of proposed changes

Add how to update PyGMT stable and dev version and some tiny improvements.

Fixes #

Reminders

• Run make format and make check to make sure the code follows the style guide.
• Add tests for new features or tests that would have caught the bug that you're fixing.
• Add new public functions/methods/classes to doc/api/index.rst.
• Write detailed docstrings for all functions/methods.
• If adding new functionality, add an example to docstrings or tutorials.

Slash Commands

You can write slash commands (/command) in the first line of a comment to perform
specific operations. Supported slash commands are:

• /format: automatically format and lint the code
• /test-gmt-dev: run full tests on the latest GMT development version

[weiji14]

Would it be possible to move the update steps into its own dedicated section? The Using pip subsection has 5 pip install ... lines and it might be overwhelming to people on why there are so many ways to pip install PyGMT!

[seisman]

Would it be possible to move the update steps into its own dedicated section? The Using pip subsection has 5 pip install ... lines and it might be overwhelming to people on why there are so many ways to pip install PyGMT!

I agree that this subsection is too long to read. I think we can remove "pip install from github":

pip install git+https://github.com/GenericMappingTools/pygmt.git#egg=pygmt

because it works the same as "pip install from TestPyPI" (it's different, but is the same for users):

pip install --pre --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple pygmt

As for upgrading PyGMT, instead of showing the long commands, I think we can simply say something like:

To upgrade the installed development version to be the latest one, just add --upgrade option
to the pip install command.

[seisman]

Some other suggestions:

Line 32: should add a comma after e.g..

Line 43:

The sections below provide more detailed, step by step instructions to installing and testing PyGMT for those who may have a slightly different setup or want to install the latest development version.

Is the above sentence correct? Should we change "to installing and testing" to "to install and test"?

Line 92:

IPython: For embedding the figures in Jupyter notebooks.

I think we should recommend Jupyter or JupyterLab, not IPython.

[core-man]

Line 32: should add a comma after e.g..

Line 43:

The sections below provide more detailed, step by step instructions to installing and testing PyGMT for those who may have a slightly different setup or want to install the latest development version.

Is the above sentence correct? Should we change "to installing and testing" to "to install and test"?

done in 49165b1.

[core-man]

Would it be possible to move the update steps into its own dedicated section? The Using pip subsection has 5 pip install ... lines and it might be overwhelming to people on why there are so many ways to pip install PyGMT!

I agree that this subsection is too long to read. I think we can remove "pip install from github":

pip install git+https://github.com/GenericMappingTools/pygmt.git#egg=pygmt

because it works the same as "pip install from TestPyPI" (it's different, but is the same for users):

pip install --pre --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple pygmt

Remove "pip install from GitHub" done in 4580e0d.

As for upgrading PyGMT, instead of showing the long commands, I think we can simply say something like:

To upgrade the installed development version to be the latest one, just add --upgrade option
to the pip install command.

Simplify PyGMT update by pip in d5b4ed9.

[core-man]

Line 92:

IPython: For embedding the figures in Jupyter notebooks.

I think we should recommend Jupyter or JupyterLab, not IPython.

Actually, we mention IPython in many places (e.g., https://www.pygmt.org/dev/tutorials/first-figure.html). I agree that it's better to recommend JupyterLab. @weiji14 how do you think?

[michaelgrund]

Line 92:

IPython: For embedding the figures in Jupyter notebooks.

I think we should recommend Jupyter or JupyterLab, not IPython.

Actually, we mention IPython in many places (e.g., https://www.pygmt.org/dev/tutorials/first-figure.html). I agree that it's better to recommend JupyterLab. @weiji14 how do you think?

Should we also differentiate between Jupyter notebooks and JupyterLab? Currently, a lot of people still work with notebooks without using them in JupyterLab.

[core-man]

Line 92:

IPython: For embedding the figures in Jupyter notebooks.

I think we should recommend Jupyter or JupyterLab, not IPython.

Actually, we mention IPython in many places (e.g., https://www.pygmt.org/dev/tutorials/first-figure.html). I agree that it's better to recommend JupyterLab. @weiji14 how do you think?

Should we also differentiate between Jupyter notebooks and JupyterLab? Currently, a lot of people still work with notebooks without using them in JupyterLab.

Shall we just recommend Jupyter, so the GMT user may choose which of JupyterLab or Jupyter Notebook they prefer?

[seisman]

Here is what I understand about the chaos:

• IPython Notebook: The first generation of "notebooks". It was renamed to "Jupyter Notebook" a few years ago. We can still run ipython notebook but it's deprecated and will be removed in future versions.
• Jupyter Notebook: The 2nd generation of "notebooks". It's still maintained but users are encouraged to transition to JupyerLab. However, there are still many users.
• JupyterLab: The 3rd and the latest generation of "notebooks".

I think we should:

1. Recommend JupyterLab in the installation guide.
2. In the tutorial notes, we should say,

This tutorial assumes the use of a Python notebook, such as JupyterLab, Jupyter Notebook, or IPython Notebook.

However, please note that, after we finish and merge #529, we will remove the notes from all tutorials, because Figure.show() should work for any running environments.

[seisman]

BTW, I don't think our main users are Python newbies, as we use many high-level packages like numpy and pandas in the documentation. I expect that our users at least have some basic knowledge about Python, numpy, pandas, and also should have their own preferences about Jupyter Notebook or JupytereLab.

[seisman]

Looks good to me.

Ping @michaelgrund @willschlitzer @weiji14 for comments and approval.

[michaelgrund]

Execpt the minor suggestion I provided, the PR looks fine for me.

[weiji14]

Just double checking that we really want to remove this install option?

[seisman]

For most users, it's the same as

pip install --pre --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple pygmt

but slower.

I don't see any reasons to keep it.

[weiji14]

Ok, fine with removing it. I just think the pip install git+https option is nice when you want to install from a GitHub branch (but that's not what we're doing here).