DOC: heading style

Author: timhoffm

doc/devel/coding_guide.rst

@@ -190,8 +190,8 @@ local arguments and the rest are passed on as
 
 .. _using_logging:
 
-Using logging for debug messages
-================================
+Use logging for debug messages
+==============================
 
 Matplotlib uses the standard Python `logging` library to write verbose
 warnings, information, and debug messages. Please use it! In all those places

doc/devel/min_dep_policy.rst

@@ -157,8 +157,8 @@ Matplotlib  Python    NumPy
 .. _`1.3`: https://matplotlib.org/1.3.0/users/installing.html#build-requirements
 
 
-Updating Python and NumPy versions
-==================================
+Update Python and NumPy versions
+================================
 
 To update the minimum versions of Python we need to update:
 

doc/devel/release_guide.rst

@@ -45,7 +45,7 @@ versioning scheme: *macro.meso.micro*.
 
 .. _release_feature_freeze:
 
-Making the release branch
+Create the release branch
 =========================
 
 .. note::
@@ -379,8 +379,8 @@ to the VER-doc branch and push to GitHub. ::
 
 .. _release_bld_bin:
 
-Building binaries
-=================
+Build binaries
+==============
 
 We distribute macOS, Windows, and many Linux wheels as well as a source tarball via
 PyPI.
@@ -412,8 +412,8 @@ PyPI.
 
 .. _release_upload_bin:
 
-Manually uploading to PyPI
-==========================
+Manual upload to PyPI
+=====================
 
 .. note::
 

doc/devel/style_guide.rst

@@ -176,6 +176,51 @@ reliability and consistency in documentation. They are not interchangeable.
 .. |Axis| replace:: :class:`~matplotlib.axis.Axis`
 
 
+Headings
+--------
+Use sentence case for headings.
+
+.. table::
+   :width: 100%
+   :widths: 50, 50
+
+   +------------------------------------+------------------------------------+
+   | Correct                            | Incorrect                          |
+   +====================================+====================================+
+   | Quick start guide                  | Quick Start Guide                  |
+   +------------------------------------+------------------------------------+
+
+Noun phrases and verb phrases are both acceptable for headings. Noun phrases
+are preferred for higher-level headings and descriptive sections as they
+simply state the content.
+
+.. table::
+   :width: 100%
+   :widths: 50, 50
+
+   +------------------------------------+------------------------------------+
+   | Correct                            | Incorrect                          |
+   +====================================+====================================+
+   | Bug triage and issue curation      | Triage bugs and curate issues      |
+   +------------------------------------+------------------------------------+
+
+Verb phrases are preferred for instructive and action-oriented sections; in
+particular when they cover steps in a process, such as the subsections in
+:ref:`installing_for_devs`.
+
+Use the second-person imperative form of the verb rather than the gerund form.
+
+.. table::
+   :width: 100%
+   :widths: 50, 50
+
+   +------------------------------------+------------------------------------+
+   | Correct                            | Incorrect                          |
+   +====================================+====================================+
+   | Fork the Matplotlib repository     | Forking the Matplotlib repository  |
+   +------------------------------------+------------------------------------+
+
+
 Grammar
 -------
 

doc/devel/testing.rst

@@ -13,10 +13,8 @@ testing infrastructure are in :mod:`matplotlib.testing`.
 .. _pytest-xdist: https://pypi.org/project/pytest-xdist/
 
 
-.. _testing_requirements:
-
-Requirements
-------------
+Prerequisites
+-------------
 
 To run the tests you will need to
 :ref:`set up Matplotlib for development <installing_for_devs>`. Note in
@@ -34,8 +32,8 @@ particular the :ref:`additional dependencies <test-dependencies>` for testing.
 
 .. _run_tests:
 
-Running the tests
------------------
+Run the tests
+-------------
 
 In the root directory of your development repository run::
 
@@ -82,8 +80,8 @@ to avoid clashes between ``pytest``'s import mode and Python's search path:
 
       python -m pytest --import-mode prepend
 
-Viewing image test output
-^^^^^^^^^^^^^^^^^^^^^^^^^
+View image test output
+^^^^^^^^^^^^^^^^^^^^^^
 
 The output of :ref:`image-based <image-comparison>` tests is stored in a
 ``result_images`` directory. These images can be compiled into one HTML page, containing
@@ -100,8 +98,8 @@ to the folder where the baseline test images are stored. The triage tool require
 :ref:`QT <backend_dependencies>` is installed.
 
 
-Writing tests
--------------
+Write tests
+-----------
 Tests are located in :file:`lib/matplotlib/tests`. They are organized to mirror
 the structure of the code in :file:`lib/matplotlib`. For example, tests for
 the ``mathtext.py`` module are in :file:`lib/matplotlib/tests/test_mathtext.py`.
@@ -284,8 +282,8 @@ See the documentation of `~matplotlib.testing.decorators.image_comparison` and
 `~matplotlib.testing.decorators.check_figures_equal` for additional information
 about their use.
 
-Using GitHub Actions for CI
----------------------------
+CI with GitHub Actions
+----------------------
 
 `GitHub Actions <https://docs.github.com/en/actions>`_ is a hosted CI system
 "in the cloud".
@@ -311,8 +309,8 @@ https://github.com/your_GitHub_user_name/matplotlib/actions -- here's `an
 example <https://github.com/QuLogic/matplotlib/actions>`_.
 
 
-Using tox
----------
+tox: Test multiple python versions
+----------------------------------
 
 `Tox <https://tox.readthedocs.io/en/latest/>`_ is a tool for running tests
 against multiple Python environments, including multiple versions of Python
@@ -352,17 +350,17 @@ tests are run. For more info on the ``tox.ini`` file, see the `Tox
 Configuration Specification
 <https://tox.readthedocs.io/en/latest/config.html>`_.
 
-Building old versions of Matplotlib
------------------------------------
+Build old versions of Matplotlib
+--------------------------------
 
 When running a ``git bisect`` to see which commit introduced a certain bug,
 you may (rarely) need to build very old versions of Matplotlib.  The following
 constraints need to be taken into account:
 
 - Matplotlib 1.3 (or earlier) requires numpy 1.8 (or earlier).
 
-Testing released versions of Matplotlib
----------------------------------------
+Test released versions of Matplotlib
+------------------------------------
 Running the tests on an installation of a released version (e.g. PyPI package
 or conda package) also requires additional setup.
 

doc/devel/triage.rst

@@ -1,9 +1,9 @@
 
 .. _bug_triaging:
 
-*******************************
-Bug triaging and issue curation
-*******************************
+*****************************
+Bug triage and issue curation
+*****************************
 
 The `issue tracker <https://github.com/matplotlib/matplotlib/issues>`_
 is important to communication in the project because it serves as the
@@ -107,8 +107,8 @@ important tasks:
     question or has been considered as unclear for many years, then it
     should be closed.
 
-Preparing PRs for review
-========================
+Prepare PRs for review
+======================
 
 Reviewing code is also encouraged. Contributors and users are welcome to
 participate to the review process following our :ref:`review guidelines