matplotlib
diff --git a/‎doc/devel/documenting_mpl.rst‎
Lines changed: 17 additions & 2 deletions b/‎doc/devel/documenting_mpl.rst‎
Lines changed: 17 additions & 2 deletions
diff --git a/‎doc/index.rst‎
Lines changed: 10 additions & 12 deletions b/‎doc/index.rst‎
Lines changed: 10 additions & 12 deletions
@@ -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
 ~~~~~~~~~~~~~~~~~~
 
 
@@ -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,26 +83,22 @@ 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!
 
 - 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>`_.