@@ -6,6 +6,11 @@ Style Guide
66This guide is for contributors to understand conventions and expectations for
77quality control of Matplotlib written content.
88
9+ .. seealso ::
10+
11+ For more information about contributing, see the :ref: `documenting-matplotlib `
12+ section.
13+
914Expository Language
1015===================
1116
@@ -137,15 +142,64 @@ references and subordinating conjunctive phrases.
137142Formatting
138143==========
139144
145+ The following guidelines specify how to incorporate code and use appropriate
146+ formatting for Matplotlib documentation.
147+
148+ Code
149+ ----
150+
151+ Matplotlib is a Python library and follows the same standards for
152+ documentation.
153+
154+ Comments
155+ ^^^^^^^^
156+ Examples of Python code have comments before or on the same line.
157+
158+ +---------------------------------------+---------------------------------+
159+ | Correct | Incorrect |
160+ +=======================================+=================================+
161+ | :: | :: |
162+ | | |
163+ | # Data | years = [2006, 2007, 2008] |
164+ | years = [2006, 2007, 2008] | # Data |
165+ +---------------------------------------+ |
166+ | :: | |
167+ | | |
168+ | years = [2006, 2007, 2008] # Data | |
169+ +---------------------------------------+---------------------------------+
170+
171+ Outputs
172+ ^^^^^^^
173+ When generating visuals with Matplotlib using ``.py `` files in examples,
174+ display the visual with ``show() `` to provide display the visual.
175+ Keep the documentation clear of Python output lines.
176+
177+ +------------------------------------+------------------------------------+
178+ | Correct | Incorrect |
179+ +====================================+====================================+
180+ | :: | :: |
181+ | | |
182+ | plt.plot([1, 2, 3], [1, 2, 3]) | plt.plot([1, 2, 3], [1, 2, 3]) |
183+ | plt.show() | |
184+ +------------------------------------+------------------------------------+
185+ | :: | :: |
186+ | | |
187+ | fig, ax = plt.subplots() | fig, ax = plt.subplots() |
188+ | ax.plot([1, 2, 3], [1, 2, 3]) | ax.plot([1, 2, 3], [1, 2, 3]) |
189+ | fig.show() | |
190+ +------------------------------------+------------------------------------+
191+
192+ reStructuredText
193+ ----------------
194+
140195Matplotlib uses reStructuredText Markup for documentation. Sphinx helps to
141196transform these documents into appropriate formats for accessibility and
142197visibility.
143198
144- reStructuredText standards
145- --------------------------
146199- `reStructuredText Specifications <https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html >`_
147200- `Quick Reference Document <https://docutils.sourceforge.io/docs/user/rst/quickref.html >`_
148201
202+
149203Lists
150204^^^^^
151205Bulleted lists are for items that do not require sequencing. Numbered lists are
0 commit comments