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!

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.

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.

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.

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.

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?

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.

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?

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.

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.