Fix header links and sphinx warnings (#1768)

Author: Meghan Jones

doc/api/index.rst

@@ -258,7 +258,7 @@ Most calls to the C API happen through the :class:`pygmt.clib.Session` class.
 
     clib.Session
 
-`GMT modules <https://docs.generic-mapping-tools.org/latest/modules.html>`__ are executed through
+:gmt-docs:`GMT modules <modules.html>` are executed through
 the :meth:`~pygmt.clib.Session.call_module` method:
 
 .. autosummary::

doc/conf.py

@@ -34,6 +34,9 @@
 # Autosummary pages will be generated by sphinx-autogen instead of sphinx-build
 autosummary_generate = []
 
+# Auto-generate header anchors with MyST parser
+myst_heading_anchors = 4
+
 # Make the list of returns arguments and attributes render the same as the
 # parameters list
 napoleon_use_rtype = False

doc/contributing.md

@@ -90,14 +90,14 @@ where you can submit general comments and/or questions:
 * For general comments, select *New Topic* from the
   [Lounge Page](https://forum.generic-mapping-tools.org/c/lounge/6).
 * To share your work, select *New Topic* from the
-  [Showcase Page](https://forum.generic-mapping-tools.org/c/Sow-your-nice-example-script/10).
+  [Showcase Page](https://forum.generic-mapping-tools.org/c/Show-your-nice-example-script/10).
 
 ## General Guidelines
 
 ### Resources for New Contributors
 
 Please take a look at these resources to learn about Git and pull requests (don't
-hesitate to [ask questions](#getting-help)):
+hesitate to [ask questions](contributing.md#getting-help)):
 
 * [How to Contribute to Open Source](https://opensource.guide/how-to-contribute/).
 * [Git Workflow Tutorial](http://www.asmeurer.com/git-workflow/) by Aaron Meurer.
@@ -161,29 +161,30 @@ To increase the chances of getting your pull request accepted quickly, try to:
   - Write some documentation for your code (docstrings) and leave comments
     explaining the *reason* behind non-obvious things.
   - Write tests for the code you wrote/modified if needed.
-    Please refer to [Testing your code](#testing-your-code) or
-    [Testing plots](#testing-plots).
+    Please refer to [Testing your code](contributing.md#testing-your-code) or
+    [Testing plots](contributing.md#testing-plots).
   - Include an example of new features in the gallery or tutorials.
-    Please refer to [Gallery plots](#gallery-plots) or [Tutorials](#tutorials).
+    Please refer to [Gallery plots](contributing.md#contributing-gallery-plots)
+    or [Tutorials](contributing.md#contributing-tutorials).
 * Have a good coding style
   - Use readable code, as it is better than clever code (even with comments).
   - Follow the [PEP8](http://pep8.org) style guide for code and the
     [NumPy style guide](https://numpydoc.readthedocs.io/en/latest/format.html)
-    for docstrings. Please refer to [Code style](#code-style).
+    for docstrings. Please refer to [Code style](contributing.md#code-style).
 
 Pull requests will automatically have tests run by GitHub Actions.
 This includes running both the unit tests as well as code linters.
 GitHub will show the status of these checks on the pull request.
 Try to get them all passing (green).
 If you have any trouble, leave a comment in the PR or
-[get in touch](#how-can-i-talk-to-you).
+[get in touch](contributing.md#getting-help).
 
 ## Setting up your Environment
 
 These steps for setting up your environment are necessary for
-[editing the documentation locally](#editing-the-documentation-locally) and
-[contributing code](#contributing-code). A local PyGMT development environment
-is not needed for [editing the documentation on GitHub](#editing-the-documentation-on-github).
+[editing the documentation locally](contributing.md#editing-the-documentation-locally) and
+[contributing code](contributing.md#contributing-code). A local PyGMT development environment
+is not needed for [editing the documentation on GitHub](contributing.md#editing-the-documentation-on-github).
 
 We highly recommend using [Anaconda](https://www.anaconda.com/download/) and the `conda`
 package manager to install and manage your Python packages.
@@ -244,24 +245,24 @@ There are four main components to PyGMT's documentation:
 The documentation are written primarily in
 [reStructuredText](https://docutils.sourceforge.io/rst.html) and built by
 [Sphinx](http://www.sphinx-doc.org/). Please refer to
-[reStructuredText Cheatsheet](https://docs.generic-mapping-tools.org/latest/devdocs/rst-cheatsheet.html)
+{gmt-docs}`reStructuredText Cheatsheet <devdocs/rst-cheatsheet.html>`
 if you are new to reStructuredText. When contributing documentation, be sure to
-follow the general guidelines in the [pull request workflow](#pull-request-workflow)
+follow the general guidelines in the [pull request workflow](contributing.md#pull-request-workflow)
 section.
 
 There are two primary ways to edit the PyGMT documentation:
 - For simple documentation changes, you can easily
-  [edit the documentation on GitHub](#editing-the-documentation-on-github).
+  [edit the documentation on GitHub](contributing.md#editing-the-documentation-on-github).
   This only requires you to have a GitHub account.
 - For more complicated changes, you can
-  [edit the documentation locally](#editing-the-documentation-locally).
+  [edit the documentation locally](contributing.md#editing-the-documentation-locally).
   In order to build the documentation locally, you first need to
-  [set up your environment](#setting-up-your-environment).
+  [set up your environment](contributing.md#setting-up-your-environment).
 
 ### Editing the Documentation on GitHub
 
 If you're browsing the documentation and notice a typo or something that could be
-improved, please consider letting us know by [creating an issue](#reporting-a-bug) or
+improved, please consider letting us know by [creating an issue](contributing.md#reporting-a-bug) or
 (even better) submitting a fix.
 
 You can submit fixes to the documentation pages completely online without having to
@@ -288,14 +289,14 @@ download and install anything:
 9. Done!
 
 Alternatively, you can make the changes offline to the files in the `doc` folder or the
-example scripts. See [editing the documentation locally](#editing-the-documentation-locally)
+example scripts. See [editing the documentation locally](contributing.md#editing-the-documentation-locally)
 for instructions.
 
 ### Editing the Documentation Locally
 
 For more extensive changes, you can edit the documentation in your cloned repository
 and build the documentation to preview changes before submitting a pull request. First,
-follow the [setting up your environment](#setting-up-your-environment) instructions.
+follow the [setting up your environment](contributing.md#setting-up-your-environment) instructions.
 After making your changes, you can build the HTML files from sources using:
 
 ```bash
@@ -305,15 +306,15 @@ make all
 
 This will build the HTML files in `doc/_build/html`.
 Open `doc/_build/html/index.html` in your browser to view the pages. Follow the
-[pull request workflow](#pull-request-workflow) to submit your changes for review.
+[pull request workflow](contributing.md#pull-request-workflow) to submit your changes for review.
 
 ### Contributing Gallery Plots
 
 The gallery and tutorials are managed by
 [sphinx-gallery](https://sphinx-gallery.readthedocs.io/).
 The source files for the example gallery are `.py` scripts in `examples/gallery/` that
 generate one or more figures. They are executed automatically by sphinx-gallery when
-the [documentation is built](#building-the-documentation). The output is gathered and
+the [documentation is built](contributing.md#editing-the-documentation-locally). The output is gathered and
 assembled into the gallery.
 
 You can **add a new** plot by placing a new `.py` file in one of the folders inside the
@@ -421,11 +422,10 @@ Linking to the GMT documentation and GMT configuration parameters can be done us
 - <code>:gmt-term:\`GMT_PARAMETER\`</code>
 
 An example would be using
-<code>:gmt-docs:\`makecpt.html\`</code> to link to
-[https://docs.generic-mapping-tools.org/latest/makecpt.html](https://docs.generic-mapping-tools.org/latest/makecpt.html).
+<code>:gmt-docs:\`makecpt.html\`</code> to link to {gmt-docs}`makecpt.html`.
 For GMT configuration parameters, an example is
 <code>:gmt-term:\`COLOR_FOREGROUND\`</code> to link to
-[https://docs.generic-mapping-tools.org/latest/gmt.conf.html#term-COLOR_FOREGROUND](https://docs.generic-mapping-tools.org/latest/gmt.conf.html#term-COLOR_FOREGROUND).
+{gmt-term}`https://docs.generic-mapping-tools.org/latest/gmt.conf#term-COLOR_FOREGROUND <COLOR_FOREGROUND>`.
 
 Sphinx will create a link to the automatically generated page for that
 function/class/module.
@@ -436,7 +436,7 @@ function/class/module.
 
 The source code for PyGMT is located in the `pygmt/` directory. When contributing
 code, be sure to follow the general guidelines in the
-[pull request workflow](#pull-request-workflow) section.
+[pull request workflow](contributing.md#pull-request-workflow) section.
 
 ### Code Style
 

doc/install.rst

@@ -53,7 +53,7 @@ latest released version that can be found at
 the `GMT official site <https://www.generic-mapping-tools.org>`__.
 We need the latest GMT (>=6.3.0) since there are many changes being made to GMT
 itself in response to the development of PyGMT, mainly the new
-`modern execution mode <https://docs.generic-mapping-tools.org/latest/cookbook/introduction.html#modern-and-classic-mode>`__.
+:gmt-docs:`modern execution mode <cookbook/introduction.html#modern-and-classic-mode>`.
 
 Compiled conda packages of GMT for Linux, macOS and Windows are provided
 through `conda-forge <https://anaconda.org/conda-forge/gmt>`__.