Documentation style guide#

Template

Template for further usage, template belong to matplotlib.

This guide contains best practices for the language and formatting of Matplotlib documentation.

Expository language#

For explanatory writing, the following guidelines are for clear and concise language use.

Terminology#

There are several key terms in Matplotlib that are standards for reliability and consistency in documentation. They are not interchangeable.

Term	Description	Correct	Incorrect
`Figure`	Matplotlib working space for programming.	For Matplotlib objects: Figure, “The Figure is the working space for the visual. Referring to class: `Figure`, “Methods within the `Figure` provide the visuals.” General language: figure, “Michelle Kwan is a famous figure skater.”	“The figure is the working space for visuals.” “Methods in the figure provide the visuals.” “The `Figure` Four leglock is a wrestling move.”
`Axes`	Subplots within Figure. Contains plot elements and is responsible for plotting and configuring additional details.	For Matplotlib objects: Axes, “An Axes is a subplot within the Figure.” Referring to class: `Axes`, “Each `Axes` is specific to one Figure.” General language: axes, “Both loggers and lumberjacks use axes to chop wood.” OR “There are no standard names for the coordinates in the three axes.” (Plural of axis)	“The axes methods transform the data.” “Each `Axes` is specific to a Figure.” “The musicians on stage call their guitars Axes.” “The point where the Axes meet is the origin of the coordinate system.”
`Artist`	Broad variety of Matplotlib objects that display visuals.	For Matplotlib objects: Artist, “Artists display visuals and are the visible elements when rendering a Figure.” Referring to class: `Artist` , “Each `Artist` has respective methods and functions.” General language: artist, “The artist in the museum is from France.”	“Configure the legend artist with its respective method.” “There is an `Artist` for that visual in the graph.” “Some Artists became famous only by accident.”
`Axis`	Human-readable single dimensional object of reference marks containing ticks, tick labels, spines, and edges.	For Matplotlib objects: Axis, “The Axis for the bar chart is a separate Artist.” (plural, Axis objects) Referring to class: `Axis`, “The `Axis` contains respective XAxis and YAxis objects.” General language: axis, “Rotation around a fixed axis is a special case of rotational motion.”	“Plot the graph onto the axis.” “Each Axis is usually named after the coordinate which is measured along it.” “In some computer graphics contexts, the ordinate `Axis` may be oriented downwards.”
Axes interface	Usage pattern in which one calls methods on Axes and Figure (and sometimes other Artist) objects to configure the plot.	Axes interface call methods on the Axes / Figure object	explicit interface object oriented OO-style OOP
pyplot interface	Usage pattern in which one only calls `.pyplot` functions to configure the plot.	`pyplot` interface call `pyplot` functions	implicit interface MATLAB like Pyplot

Grammar#

Subject#

Use second-person imperative sentences for directed instructions specifying an action. Second-person pronouns are for individual-specific contexts and possessive reference.

Correct	Incorrect
Install Matplotlib from the source directory using the Python `pip` installer program. Depending on your operating system, you may need additional support.	You can install Matplotlib from the source directory. You can find additional support if you are having trouble with your installation.

Tense#

Use present simple tense for explanations. Avoid future tense and other modal or auxiliary verbs when possible.

Correct	Incorrect
The fundamental ideas behind Matplotlib for visualization involve taking data and transforming it through functions and methods.	Matplotlib will take data and transform it through functions and methods. They can generate many kinds of visuals. These will be the fundamentals for using Matplotlib.

Voice#

Write in active sentences. Passive voice is best for situations or conditions related to warning prompts.

Correct	Incorrect
The function `plot` generates the graph.	The graph is generated by the `plot` function.
An error message is returned by the function if there are no arguments.	You will see an error message from the function if there are no arguments.

Sentence structure#

Write with short sentences using Subject-Verb-Object order regularly. Limit coordinating conjunctions in sentences. Avoid pronoun references and subordinating conjunctive phrases.

Correct	Incorrect
The `pyplot` module in Matplotlib is a collection of functions. These functions create, manage, and manipulate the current Figure and plotting area.	The `pyplot` module in Matplotlib is a collection of functions which create, manage, and manipulate the current Figure and plotting area.
The `plot` function plots data to the respective Axes. The Axes corresponds to the respective Figure.	The `plot` function plots data within its respective Axes for its respective Figure.
The implicit approach is a convenient shortcut for generating simple plots.	Users that wish to have convenient shortcuts for generating plots use the implicit approach.

Formatting#

The following guidelines specify how to incorporate code and use appropriate formatting for Matplotlib documentation.

Code#

Matplotlib is a Python library and follows the same standards for documentation.

Comments#

Examples of Python code have comments before or on the same line.

Correct	Incorrect
# Data years = [2006, 2007, 2008]	years = [2006, 2007, 2008] # Data
years = [2006, 2007, 2008] # Data	years = [2006, 2007, 2008] # Data

Outputs#

When generating visuals with Matplotlib using .py files in examples, display the visual with matplotlib.pyplot.show to display the visual. Keep the documentation clear of Python output lines.

Correct	Incorrect
plt.plot([1, 2, 3], [1, 2, 3]) plt.show()	plt.plot([1, 2, 3], [1, 2, 3])
fig, ax = plt.subplots() ax.plot([1, 2, 3], [1, 2, 3]) fig.show()	fig, ax = plt.subplots() ax.plot([1, 2, 3], [1, 2, 3])

reStructuredText#

Matplotlib uses reStructuredText Markup for documentation. Sphinx helps to transform these documents into appropriate formats for accessibility and visibility.

Lists#

Bulleted lists are for items that do not require sequencing. Numbered lists are exclusively for performing actions in a determined order.

Correct	Incorrect
The example uses three graphs.	The example uses three graphs.
Bar Line Pie	Bar Line Pie
These four steps help to get started using Matplotlib.	The following steps are important to get started using Matplotlib.
Import the Matplotlib library. Import the necessary modules. Set and assign data to work on. Transform data with methods and functions.	Import the Matplotlib library. Import the necessary modules. Set and assign data to work on. Transform data with methods and functions.

Tables#

Use ASCII tables with reStructuredText standards in organizing content. Markdown tables and the csv-table directive are not accepted.

Correct

Incorrect

Correct	Incorrect
OK	Not OK

| Correct | Incorrect |
| ------- | --------- |
| OK      | Not OK    |

+----------+----------+
| Correct  | Incorrect|
+==========+==========+
| OK       | Not OK   |
+----------+----------+

.. csv-table::
   :header: "correct", "incorrect"
   :widths: 10, 10

   "OK   ", "Not OK"

===========  ===========
  Correct     Incorrect
===========  ===========
OK           Not OK
===========  ===========

Additional resources#

This style guide is not a comprehensive standard. For a more thorough reference of how to contribute to documentation, see the links below. These resources contain common best practices for writing documentation.