DOC: Improve docs on writing documentation

Author: timhoffm

doc/devel/document.rst

@@ -154,8 +154,8 @@ for opening them in your default browser is:
 
 .. _writing-rest-pages:
 
-Write ReST pages
-================
+reStructuredText pages
+======================
 
 Most documentation is either in the docstrings of individual
 classes and methods, in explicit ``.rst`` files, or in examples and tutorials.
@@ -243,11 +243,15 @@ nor the ````literal```` role:
    Do not describe ``argument`` like this.
 
 
-Write mathematical expressions
-------------------------------
+Mathematical expressions
+------------------------
+Use sphinx's built in math support:
+
+- **Inline math:** Use the ``:math:``
+  `role <https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#math>`__
+- **Math blocks:** Use the ``.. math::``
+  `directive <https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#math>`__
 
-In most cases, you will likely want to use one of `Sphinx's builtin Math
-extensions <https://www.sphinx-doc.org/en/master/usage/extensions/math.html>`__.
 In rare cases we want the rendering of the mathematical text in the
 documentation html to exactly match with the rendering of the mathematical
 expression in the Matplotlib figure. In these cases, you can use the
@@ -257,8 +261,8 @@ expression in the Matplotlib figure. In these cases, you can use the
 
 .. _internal-section-refs:
 
-Refer to other documents and sections
--------------------------------------
+Cross-references
+----------------
 
 Sphinx_ supports internal references_:
 
@@ -277,63 +281,55 @@ Role        Links target     Representation in rendered HTML
 .. |ref-dir| replace:: ``:ref:``
 .. _ref-dir: https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-ref
 
-Examples:
+Document cross-references ``:doc:``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-.. code-block:: rst
+To cross-link to another page, use the ``:doc:`` role. We generally prefer
+absolute paths, starting with ``/`` as the :file:``doc`` root directory.
 
-   See the :doc:`/install/index`
+Example:
 
-   See the tutorial :ref:`quick_start`
+.. code-block:: rst
 
-   See the example :doc:`/gallery/lines_bars_and_markers/simple_plot`
+   See the :doc:`/install/index`
 
 will render as:
 
   See the :doc:`/install/index`
 
-  See the tutorial :ref:`quick_start`
+Section cross-references ``:ref:``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-  See the example :doc:`/gallery/lines_bars_and_markers/simple_plot`
+To cross-link a specific section, add a reference label before the section
 
-Sections can also be given reference labels.  For instance from the
-:doc:`/install/index` link:
 
 .. code-block:: rst
 
-   .. _clean-install:
+   .. _pr-author-guidelines:
 
-   How to completely remove Matplotlib
-   ===================================
+   Summary for pull request authors
+   ================================
 
-   Occasionally, problems with Matplotlib can be solved with a clean...
-
-and refer to it using the standard reference syntax:
+and then link to with the ``:ref:`` role
 
 .. code-block:: rst
 
-   See :ref:`clean-install`
-
-will give the following link: :ref:`clean-install`
+   See the :ref:`pr-author-guidelines`
 
-To maximize internal consistency in section labeling and references,
-use hyphen separated, descriptive labels for section references.
-Keep in mind that contents may be reorganized later, so
-avoid top level names in references like ``user`` or ``devel``
-or ``faq`` unless necessary, because for example the FAQ "what is a
-backend?" could later become part of the users guide, so the label:
+This with render as:
 
-.. code-block:: rst
+    See the :ref:`pr-author-guidelines`
 
-   .. _what-is-a-backend:
+Use hyphen-separated, descriptive names for reference labels.
+Do not encode the documentation hierarchy in the label as that may change;
+e.g. do not prefix all *User guide* labels with ``user-``.
 
-is better than:
+Example:
 
-.. code-block:: rst
+.. code-block::
 
-   .. _faq-backend:
+   .. _pr-author-guidelines:
 
-In addition, since underscores are widely used by Sphinx itself, use
-hyphens to separate words.
 
 .. _referring-to-other-code:
 
@@ -461,8 +457,8 @@ For clarity, do not use relative links.
 
 .. _writing-docstrings:
 
-Write API documentation
-=======================
+API documentation
+=================
 
 The API reference documentation describes the library interfaces, e.g. inputs, outputs,
 and expected behavior. Most of the API documentation is written in docstrings. These are
@@ -957,8 +953,8 @@ Example:
 
 .. _writing-examples-and-tutorials:
 
-Write examples and tutorials
-============================
+Examples and tutorials
+======================
 
 Examples and tutorials are Python scripts that are run by `Sphinx Gallery`_.
 Sphinx Gallery finds ``*.py`` files in source directories and runs the files to
@@ -1226,10 +1222,10 @@ Format
 :code: The code should be about 5-10 lines with minimal customization. Plots in
        this gallery use the ``_mpl-gallery`` stylesheet for a uniform aesthetic.
 
-Analytics
-==========
+Website analytics
+=================
 
-Documentation page analytics are available at
+Analytics of our hosted documentation https://matplotlib.org is available at
 https://views.scientific-python.org/matplotlib.org.