Documentation Link

https://matplotlib.org/devdocs/devel/document.html#section-formatting

Problem

We acknowledge in our docs that we haven't completely moved our docs over to our specified format, which sometimes creates cascading effects when trying to combine/reorganize docs- directives like ..include don't like the mismatch and when reading the docs it can make it hard to figure out what level a given section is supposed to be at.

Suggested improvement

Reformat docs as needed so that they conform to the guidelines.

Use sentence case Upper lower for section titles, e.g., Possible hangups rather than Possible Hangups.

We aim to follow the recommendations from the Python documentation and the Sphinx reStructuredText documentation for section markup characters, i.e.:

# with overline, for parts. This is reserved for the main title in doc/index.rst. 

* with overline, for chapter. all pages except doc/index.rst should start with "chapter" or lower.

=, for sections

-, for subsections

^, for subsubsections

", for paragraphs

NOTES:

• do not sentence case files under "/project"
• ignore files in any "api_changes", "whats_new", or MEP file/folder.
• do not add new headings without a justification. This issue is about converting existing heading markers into its corresponding heading markers in the list above.

Documents with old style formatting:

This work is mostly converting ~~ to ^^^
Please post here which file you are working on:

project

• user/project/citing user/project/citing updated #26995

API

• api/animation updated api/animation documentation as per standards #27348

contribute

• devel/contribute DOC: made "open PR on MPL" a section in contribute guide #26961
• devel/document DOC: separate and clarify axisartist default tables #26754
• devel/release_guide Update developer release guide to follow conventions #27118
• Formatted release note docs #27039

user_guide

• user_guide/artists/artist_intro updated artist_intro.rst #27036
• user_guide/figure/api_interfaces updated api_interfaces.rst #27043
• user_guide/figure/interactive updated interactive.rst #27054

text

• user_guide/text/text_intro make fonts.py, mathtext.py, text_intro.py confirm to docs guidelines #27096
• user_guide/text/fonts make fonts.py, mathtext.py, text_intro.py confirm to docs guidelines #27096
• user_guide/text/mathtext make fonts.py, mathtext.py, text_intro.py confirm to docs guidelines #27096

toolkits

• user_guide/toolkits/axes_grid Reformatted documentation under toolkits and tutorials directory  #26985

tutorials

• tutorials/index Reformatted documentation under toolkits and tutorials directory  #26985

gallery

• examples/subplots_axes_and_figures Updated axes_box_aspect.py and angle_annotation.py to regularize formatting #27219
• examples/text_labels_and_annotations/angle_annotation Updated axes_box_aspect.py and angle_annotation.py to regularize formatting #27219