doc: Convert the installation guides source code from ReST to Markdown (#2992)

Co-authored-by: Wei Ji <[email protected]>

Author: seisman

doc/conf.py

@@ -12,6 +12,10 @@
 
 # ruff: isort: on
 
+requires_python = metadata("pygmt")["Requires-Python"]
+with pygmt.clib.Session() as lib:
+    requires_gmt = f">={lib.required_version}"
+
 extensions = [
     "myst_parser",
     "sphinx.ext.autodoc",
@@ -34,10 +38,18 @@
 
 # Auto-generate header anchors with MyST parser
 myst_heading_anchors = 4
+# reference: https://myst-parser.readthedocs.io/en/latest/syntax/optional.html
 myst_enable_extensions = [
     "attrs_inline",  # Allow inline attributes after images
     "colon_fence",  # Allow code fences using colons
+    "substitution",  # Allow substituitions
 ]
+# These enable substitutions using {{ key }} in the Markdown files
+myst_substitutions = {
+    "requires_python": requires_python,
+    "requires_gmt": requires_gmt,
+}
+
 
 # Make the list of returns arguments and attributes render the same as the
 # parameters list
@@ -151,17 +163,6 @@
     html_baseurl = "https://pygmt.org/latest/"
 release = __version__
 
-requires_python = metadata("pygmt")["Requires-Python"]
-with pygmt.clib.Session() as lib:
-    requires_gmt = ">=" + lib.required_version
-
-# These enable substitutions using |variable| in the rst files
-rst_epilog = f"""
-.. |year| replace:: {year}
-.. |requires_python| replace:: {requires_python}
-.. |requires_gmt| replace:: {requires_gmt}
-"""
-
 html_last_updated_fmt = "%b %d, %Y"
 html_title = "PyGMT"
 html_short_title = "PyGMT"

doc/index.rst

@@ -19,7 +19,7 @@
     :caption: Getting Started
 
     overview.md
-    install.rst
+    install.md
     get_started/index.rst
 
 .. toctree::

doc/install.md

@@ -0,0 +1,282 @@
+# Installing
+
+## Quickstart
+
+The fastest way to install PyGMT is with the [mamba](https://mamba.readthedocs.io/en/latest/)
+or [conda](https://docs.conda.io/projects/conda/en/latest/user-guide/index.html)
+package manager which takes care of setting up a virtual environment, as well as the
+installation of GMT and all the dependencies PyGMT depends on:
+
+:::: {tab-set}
+::: {tab-item} mamba
+:sync: mamba
+```
+mamba create --name pygmt --channel conda-forge pygmt
+```
+:::
+
+::: {tab-item} conda
+:sync: conda
+```
+conda create --name pygmt --channel conda-forge pygmt
+```
+:::
+::::
+
+To activate the virtual environment, you can do:
+
+:::: {tab-set}
+::: {tab-item} mamba
+:sync: mamba
+```
+mamba activate pygmt
+```
+:::
+
+::: {tab-item} conda
+:sync: conda
+```
+conda activate pygmt
+```
+:::
+::::
+
+After this, check that everything works by running the following in a Python interpreter
+(e.g., in a Jupyter notebook):
+```python
+import pygmt
+pygmt.show_versions()
+```
+
+You are now ready to make you first figure! Start by looking at the tutorials on our
+sidebar, good luck!
+
+:::{note}
+The sections below provide more detailed, step by step instructions to install and test
+PyGMT for those who may have a slightly different setup or want to install the latest
+development version.
+:::
+
+## Which Python?
+
+PyGMT is tested to run on Python {{ requires_python }}.
+
+We recommend using the [Miniforge](https://github.com/conda-forge/miniforge#miniforge3)
+Python distribution to ensure you have all dependencies installed and
+the [mamba](https://mamba.readthedocs.io/en/stable/user_guide/mamba.html) package manager
+in the base environment. Installing Miniforge does not require administrative rights to
+your computer and doesn't interfere with any other Python installations on your system.
+
+## Which GMT?
+
+PyGMT requires Generic Mapping Tools (GMT) {{ requires_gmt }} since there are many
+changes being made to GMT itself in response to the development of PyGMT.
+
+Compiled conda packages of GMT for Linux, macOS and Windows are provided through
+[conda-forge](https://anaconda.org/conda-forge/gmt). Advanced users can also
+[build GMT from source](https://github.com/GenericMappingTools/gmt/blob/master/BUILDING.md)
+instead.
+
+We recommend following the instructions further on to install GMT 6.
+
+## Dependencies
+
+PyGMT requires the following libraries to be installed:
+
+- [numpy](https://numpy.org) (>= 1.23)
+- [pandas](https://pandas.pydata.org)
+- [xarray](https://xarray.dev/)
+- [netCDF4](https://unidata.github.io/netcdf4-python)
+- [packaging](https://packaging.pypa.io)
+
+The following are optional dependencies:
+
+- [IPython](https://ipython.org): For embedding the figures in Jupyter notebooks (recommended).
+- [Contextily](https://contextily.readthedocs.io): For retrieving tile maps from the internet.
+- [GeoPandas](https://geopandas.org): For using and plotting GeoDataFrame objects.
+- [RioXarray](https://corteva.github.io/rioxarray): For saving multi-band rasters to GeoTIFFs.
+
+:::{note}
+If you have [PyArrow](https://arrow.apache.org/docs/python/index.html) installed, PyGMT
+does have some initial support for `pandas.Series` and `pandas.DataFrame` objects with
+Apache Arrow-backed arrays. Specifically, only uint/int/float and date32/date64 dtypes
+are supported for now. Support for string Arrow dtypes is still a work in progress.
+For  more details, see [issue #2800](https://github.com/GenericMappingTools/pygmt/issues/2800).
+:::
+
+## Installing GMT and other dependencies
+
+Before installing PyGMT, we must install GMT itself along with the other dependencies.
+The easiest way to do this is via the `mamba` or `conda` package manager. We recommend
+working in an isolated
+[virtual environment](https://conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html)
+to avoid issues with conflicting versions of dependencies.
+
+First, we must configure conda to get packages from the [conda-forge channel](https://conda-forge.org/):
+```
+conda config --prepend channels conda-forge
+```
+
+Now we can create a new virtual environment with Python and all our dependencies
+installed (we'll call it `pygmt` but feel free to change it to whatever you want):
+
+:::: {tab-set}
+::: {tab-item} mamba
+:sync: mamba
+```
+mamba create --name pygmt python=3.12 numpy pandas xarray netcdf4 packaging gmt
+```
+:::
+
+::: {tab-item} conda
+:sync: conda
+```
+conda create --name pygmt python=3.12 numpy pandas xarray netcdf4 packaging gmt
+```
+:::
+::::
+
+Activate the environment by running the following (**do not forget this step!**):
+
+:::: {tab-set}
+::: {tab-item} mamba
+:sync: mamba
+```
+mamba activate pygmt
+```
+:::
+
+::: {tab-item} conda
+:sync: conda
+```
+conda activate pygmt
+```
+:::
+::::
+
+From now on, all commands will take place inside the virtual environment called `pygmt`
+and won't affect your default `base` installation.
+
+## Installing PyGMT
+
+Now that you have GMT installed and your virtual environment activated, you can install
+PyGMT using any of the following methods.
+
+### Using mamba/conda (recommended)
+
+This installs the latest stable release of PyGMT from [conda-forge](https://anaconda.org/conda-forge/pygmt):
+
+:::: {tab-set}
+::: {tab-item} mamba
+:sync: mamba
+```
+mamba install pygmt
+```
+:::
+
+::: {tab-item} conda
+:sync: conda
+```
+conda install pygmt
+```
+:::
+::::
+
+This upgrades the installed PyGMT version to be the latest stable release:
+
+:::: {tab-set}
+::: {tab-item} mamba
+:sync: mamba
+```
+mamba update pygmt
+```
+:::
+
+::: {tab-item} conda
+:sync: conda
+```
+conda update pygmt
+```
+:::
+::::
+
+### Using pip
+
+This installs the latest stable release from [PyPI](https://pypi.org/project/pygmt):
+```
+python -m pip install pygmt
+```
+
+::: {tip}
+You can also run `python -m pip install pygmt[all]` to install pygmt with all of its
+optional dependencies.
+:::
+
+Alternatively, you can install the latest development version from
+[TestPyPI](https://test.pypi.org/project/pygmt):
+```
+python -m pip install --pre --extra-index-url https://test.pypi.org/simple/ pygmt
+```
+
+To upgrade the installed stable release or development version to be the latest one,
+just add `--upgrade` to the corresponding command above.
+
+Any of the above methods (mamba/conda/pip) should allow you to use the PyGMT package
+from Python.
+
+## Testing your install
+
+To ensure that PyGMT and its dependencies are installed correctly, run the following
+in your Python interpreter:
+
+```python
+import pygmt
+pygmt.show_versions()
+
+fig = pygmt.Figure()
+fig.coast(region="g", frame=True, shorelines=1)
+fig.show()
+```
+
+If you see a global map with shorelines, then you're all set.
+
+## Common installation issues
+
+If you have any issues with the installation, please check out the following common
+problems and solutions.
+
+### "Error loading GMT shared library at ..."
+
+Sometimes, PyGMT will be unable to find the correct version of the GMT shared library
+(`libgmt`). This can happen if you have multiple versions of GMT installed.
+
+You can tell PyGMT exactly where to look for `libgmt` by setting the `GMT_LIBRARY_PATH`
+environment variable to the directory where `libgmt.so`, `libgmt.dylib` or `gmt.dll` can
+be found on Linux, macOS or Windows, respectively.
+
+For Linux/macOS, add the following line to your shell configuration file (usually
+`~/.bashrc` for Bash on Linux and `~/.zshrc` for Zsh on macOS):
+```
+export GMT_LIBRARY_PATH=$HOME/miniforge3/envs/pygmt/lib
+```
+
+For Windows, add the `GMT_LIBRARY_PATH` environment variable following these
+[instructions](https://www.wikihow.com/Create-an-Environment-Variable-in-Windows-10)
+and set its value to a path like:
+```
+C:\Users\USERNAME\Miniforge3\envs\pygmt\Library\bin\
+```
+
+### `ModuleNotFoundError` in Jupyter notebook environment
+
+If you can successfully import pygmt in a Python interpreter or IPython, but get a
+`ModuleNotFoundError` when importing pygmt in Jupyter, you may need to activate your
+`pygmt` virtual environment (using `mamba activate pygmt` or `conda activate pygmt`)
+and install a `pygmt` kernel following the commands below:
+```
+python -m ipykernel install --user --name pygmt  # install virtual environment properly
+jupyter kernelspec list --json
+```
+
+After that, you need to restart Jupyter, open your notebook, select the `pygmt` kernel
+and then import pygmt.