From cfa4f6bb566e1e21edaa6ec581323fa9ca5a44e4 Mon Sep 17 00:00:00 2001
From: Jody Klymak <jklymak@gmail.com>
Date: Mon, 25 Oct 2021 07:49:46 +0200
Subject: [PATCH] Backport PR #21453: Cleanup index.rst sectioning

---
 doc/devel/documenting_mpl.rst | 19 +++++++++++++++++--
 doc/index.rst                 | 22 ++++++++++------------
 2 files changed, 27 insertions(+), 14 deletions(-)

diff --git a/doc/devel/documenting_mpl.rst b/doc/devel/documenting_mpl.rst
index 2355a251be57..97a2fd4bc0bb 100644
--- a/doc/devel/documenting_mpl.rst
+++ b/doc/devel/documenting_mpl.rst
@@ -138,13 +138,28 @@ Formatting and style conventions
 It is useful to strive for consistency in the Matplotlib documentation.  Here
 are some formatting and style conventions that are used.
 
-Section name formatting
-~~~~~~~~~~~~~~~~~~~~~~~
+Section formatting
+~~~~~~~~~~~~~~~~~~
 
 For everything but top-level chapters,  use ``Upper lower`` for
 section titles, e.g., ``Possible hangups`` rather than ``Possible
 Hangups``
 
+We aim to follow the recommendations from the
+`Python documentation <https://devguide.python.org/documenting/#sections>`_
+and the `Sphinx reStructuredText documentation <https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#sections>`_
+for section markup characters, i.e.:
+
+- ``#`` with overline, for parts. This is reserved for the main title in
+  ``index.rst``. All other pages should start with "chapter" or lower.
+- ``*`` with overline, for chapters
+- ``=``, for sections
+- ``-``, for subsections
+- ``^``, for subsubsections
+- ``"``, for paragraphs
+
+This may not yet be applied consistently in existing docs.
+
 Function arguments
 ~~~~~~~~~~~~~~~~~~
 
diff --git a/doc/index.rst b/doc/index.rst
index 1ac3cfc80ecd..62e376197a4a 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -5,14 +5,16 @@
 .. module:: matplotlib
 
 
+##################################
 Matplotlib |release| documentation
-----------------------------------
+##################################
 
 Matplotlib is a comprehensive library for creating static, animated,
 and interactive visualizations in Python.
 
+************
 Installation
-============
+************
 
 .. container:: twocol
 
@@ -35,9 +37,9 @@ Installation
 Further details are available in the :doc:`Installation Guide <users/installing/index>`.
 
 
+******************
 Learning resources
-==================
-
+******************
 
 .. panels::
 
@@ -81,16 +83,18 @@ Learning resources
 
 
 
+********************
 Third-party packages
---------------------
+********************
 
 There are many `Third-party packages
 <https://matplotlib.org/mpl-third-party/>`_ built on top of and extending
 Matplotlib.
 
 
+************
 Contributing
-------------
+************
 
 Matplotlib is a community project maintained for and by its users.  There are many ways
 you can help!
@@ -98,9 +102,3 @@ you can help!
 - Help other users `on discourse <https://discourse.matplotlib.org>`__
 - report a bug or request a feature `on GitHub <https://github.com/matplotlib/matplotlib/issues>`__
 - or improve the :ref:`documentation and code <developers-guide-index>`
-
-
-Users guide
------------
-
-The `contents of the docs <users/index.html>`_.