Documentation style guide#

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

See also

For more information about contributing, see theWrite documentationsection.

Expository language#

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

Terminology#

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

Term

Description

Correct

Incorrect

Figure

Matplotlib working spacefor programming.

  • ForMatplotlibobjects:Figure,"The Figureis theworkingspace forthe visual.

  • Referringto class:Figure,"Methodswithin theFigureprovide thevisuals."

  • Generallanguage:figure,"MichelleKwan is afamousfigureskater."

  • "The figureis theworkingspace forvisuals."

  • "Methods inthe figureprovide thevisuals."

  • "TheFigureFourleglock isa wrestlingmove."

Axes

Subplots within Figure.Contains plot elementsand is responsible forplotting and configuringadditional details.

  • ForMatplotlibobjects:Axes, "AnAxes is asubplotwithin theFigure."

  • Referringto class:Axes,"EachAxes isspecific tooneFigure."

  • Generallanguage:axes, "Bothloggers andlumberjacksuse axes tochop wood."OR "Thereare nostandardnames forthecoordinatesin thethreeaxes."(Plural ofaxis)

  • "The axesmethodstransformthe data."

  • "EachAxes isspecific toa Figure."

  • "Themusicianson stagecall theirguitarsAxes."

  • "The pointwhere theAxes meetis theorigin ofthecoordinatesystem."

Artist

Broad variety ofMatplotlib objects thatdisplay visuals.

  • ForMatplotlibobjects:Artist,"Artistsdisplayvisuals andare thevisibleelementswhenrendering aFigure."

  • Referringto class:Artist ,"EachArtisthasrespectivemethods andfunctions."

  • Generallanguage:artist,"Theartist inthe museumis fromFrance."

  • "Configurethe legendartist withitsrespectivemethod."

  • "There isanArtistfor thatvisual inthe graph."

  • "SomeArtistsbecamefamous onlybyaccident."

Axis

Human-readable singledimensional objectof reference markscontaining ticks, ticklabels, spines, andedges.

  • ForMatplotlibobjects:Axis, "TheAxis forthe barchart is aseparateArtist."(plural,Axisobjects)

  • Referringto class:Axis,"TheAxiscontainsrespectiveXAxis andYAxisobjects."

  • Generallanguage:axis,"Rotationaround afixed axisis aspecialcase ofrotationalmotion."

  • "Plot thegraph ontothe axis."

  • "Each Axisis usuallynamed afterthecoordinatewhich ismeasuredalong it."

  • "In somecomputergraphicscontexts,theordinateAxis maybe orienteddownwards."

Axes interface

Usage pattern in whichone calls methods onAxes and Figure (andsometimes other Artist)objects to configure theplot.

  • Axesinterface

  • callmethods onthe Axes /Figureobject

  • explicitinterface

  • objectoriented

  • OO-style

  • OOP

pyplot interface

Usage pattern in whichone only callspyplotfunctions to configurethe plot.

  • pyplotinterface

  • callpyplotfunctions

  • implicitinterface

  • MATLAB like

  • Pyplot

Grammar#

Subject#

Use second-person imperative sentences for directed instructions specifying anaction. Second-person pronouns are for individual-specific contexts andpossessive reference.

Correct

Incorrect

Install Matplotlib from the sourcedirectory using the Pythonpipinstaller program. Depending onyour operating system, you may needadditional support.

You can install Matplotlib from thesource directory. You can findadditional support if you arehaving trouble with yourinstallation.

Tense#

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

Correct

Incorrect

The fundamental ideas behindMatplotlib for visualizationinvolve taking data andtransforming it through functionsand methods.

Matplotlib will take data andtransform it through functions andmethods. They can generate manykinds of visuals. These will be thefundamentals for using Matplotlib.

Voice#

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

Correct

Incorrect

The functionplot generates thegraph.

The graph is generated by theplot function.

An error message is returned by thefunction if there are no arguments.

You will see an error message fromthe function if there are noarguments.

Sentence structure#

Write with short sentences using Subject-Verb-Object order regularly. Limitcoordinating conjunctions in sentences. Avoid pronoun references andsubordinating conjunctive phrases.

Correct

Incorrect

Thepyplot module in Matplotlibis a collection of functions. Thesefunctions create, manage, andmanipulate the current Figure andplotting area.

Thepyplot module in Matplotlibis a collection of functions whichcreate, manage, and manipulate thecurrent Figure and plotting area.

Theplot function plots datato the respective Axes. The Axescorresponds to the respectiveFigure.

Theplot function plots datawithin its respective Axes for itsrespective Figure.

The implicit approach is aconvenient shortcut forgenerating simple plots.

Users that wish to have convenientshortcuts for generating plots usethe implicit approach.

Formatting#

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

Code#

Matplotlib is a Python library and follows the same standards fordocumentation.

Comments#

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

Correct

Incorrect

# Datayears=[2006,2007,2008]
years=[2006,2007,2008]# Data
years=[2006,2007,2008]# Data

Outputs#

When generating visuals with Matplotlib using.py files in examples,display the visual withmatplotlib.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 totransform these documents into appropriate formats for accessibility andvisibility.

Lists#

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

Correct

Incorrect

The example uses three graphs.

The example uses three graphs.

  • Bar

  • Line

  • Pie

  1. Bar

  2. Line

  3. Pie

These four steps help to getstarted using Matplotlib.

The following steps are importantto get started using Matplotlib.

  1. Import the Matplotlib library.

  2. Import the necessary modules.

  3. Set and assign data to work on.

  4. Transform data with methods andfunctions.

  • Import the Matplotlib library.

  • Import the necessary modules.

  • Set and assign data to work on.

  • Transform data with methods andfunctions.

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|NotOK|
+----------+----------+|Correct|Incorrect|+==========+==========+|OK|NotOK|+----------+----------+
..csv-table:::header:"correct","incorrect":widths:10,10"OK   ","Not OK"
======================CorrectIncorrect======================OKNotOK======================

Additional resources#

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