33Style Guide
44===========
55
6+ This guide is for contributors to understand conventions and expectations for
7+ quality control of Matplotlib written content.
8+
69Expository Language
710===================
811
12+ For explanatory writing, the following guidelines are for clear and concise
13+ language use.
14+
915Terminology
1016-----------
1117
12- +-----------------------+--------------------------+------------------------+
13- | Term | Description | |
14- +-----------------------+--------------------------+------------------------+
15- | Figure | | |
16- +-----------------------+--------------------------+------------------------+
17- | Axes | | |
18- +-----------------------+--------------------------+------------------------+
19- | Object Oriented | | |
20- | Programming (OOP) | | |
21- +-----------------------+--------------------------+------------------------+
18+ There are several key terms in Matplotlib that are standards for
19+ reliability and consistency in documentation. They are case-sensitive and
20+ are not interchangeable.
21+
22+ +----------------------+--------------------------+-------------------------+
23+ | Term | Description | Correct | Incorrect |
24+ +----------------------+--------------------------+-------------------------+
25+ | Figure | Workign space for | | |
26+ | | programming. | | |
27+ +----------------------+--------------------------+-------------------------+
28+ | Axes | Subplots within Figure. | | |
29+ | | Contains Figure elements | | |
30+ | | and is responsible for | | |
31+ | | plotting and configuring | | |
32+ | | additional details. | | |
33+ +----------------------+--------------------------+-------------------------+
34+ | Axis | Refers to visible object | | |
35+ | | corresponding to labeling| | |
36+ | | of plotted data. | | |
37+ +----------------------+--------------------------+-------------------------+
38+ | Artist | Broad Matplotlib object | | |
39+ | | that displays visuals. | | |
40+ +----------------------+--------------------------+-------------------------+
41+ | Object Oriented | Explicit approach of | | |
42+ | Programming (OOP) | programing in Matplotlib.| | |
43+ +----------------------+--------------------------+-------------------------+
2244
2345
2446Grammar
@@ -35,7 +57,11 @@ an action.
3557+------------------------------------+------------------------------------+
3658| Correct | Incorrect |
3759+------------------------------------+------------------------------------+
38- | | |
60+ | Users install Matplotlib from the | You can install Matplotlib from the|
61+ | source directory using the Python | source directory. You can find |
62+ | ``pip `` installer program. | additional support if you are |
63+ | Depending on your operating system,| having troulbe with your |
64+ | you may need additional support. | installation. |
3965+------------------------------------+------------------------------------+
4066
4167Tense
@@ -46,18 +72,27 @@ or auxiliary verbs when possible.
4672+------------------------------------+------------------------------------+
4773| Correct | Incorrect |
4874+------------------------------------+------------------------------------+
49- | | |
75+ | The fundamental ideas behind | Matplotlib will take data and |
76+ | Matplotlib for visualization | transform it through functions and |
77+ | involve taking data and | methods. This should be the basic |
78+ | transforming it thorugh functions | fundamental idea behind Matplotlib |
79+ | and methods. | for visualizations. |
5080+------------------------------------+------------------------------------+
5181
5282Voice
5383^^^^^
5484Write in active sentences. Passive voice is best for situations or condtions
55- for warning prompts.
85+ related to warning prompts.
5686
5787+------------------------------------+------------------------------------+
5888| Correct | Incorrect |
5989+------------------------------------+------------------------------------+
60- | | |
90+ | The function ``plot `` generates the| The graph is generated by the |
91+ | graph. | ``plot `` function. |
92+ +------------------------------------+------------------------------------+
93+ | An error message is returned by the| You will see an error message from |
94+ | function if there are no arguments.| the function if there are no |
95+ | | arguments. |
6196+------------------------------------+------------------------------------+
6297
6398Sentence structure
@@ -69,15 +104,31 @@ referenes and subordinating conjunctive prhases.
69104+------------------------------------+------------------------------------+
70105| Correct | Incorrect |
71106+------------------------------------+------------------------------------+
72- | | |
107+ | The ``pyplot`` module in Matplotlib| The ``pyplot`` module in Matplotlib|
108+ | is a collection of functions. These| is a collection of functions which |
109+ | functions create, manage, and | create, manage, and manipulate the |
110+ | manipulate the current Figure and | current Figure and plotting area. |
111+ | plotting area. | |
112+ +------------------------------------+------------------------------------+
113+ | The ``plot `` function plots data | The ``plot `` function plots data |
114+ | to the respective Axes. The Axes | within its respective Axes for its |
115+ | corresponds to the respective | respective Figure. |
116+ | Figure. | |
73117+------------------------------------+------------------------------------+
74118
75119Formatting
76120==========
77121
122+ Matplotlib uses reStructuredText Markup for documentation. Sphinx helps to
123+ transform these documents into proper formats for access and visibility.
124+
78125reStructuredText standards
79126--------------------------
80127
128+ https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html
129+ https://docutils.sourceforge.io/docs/user/rst/quickref.html
130+
131+
81132Lists
82133^^^^^
83134Bulleted lists are for items that do not require sequencing.
@@ -86,12 +137,29 @@ Numbered Lists are exclusively for performing actions in specific order.
86137+------------------------------------+------------------------------------+
87138| Correct | Incorrect |
88139+------------------------------------+------------------------------------+
89- | | |
140+ | The example uses three graphs. | The example uses three graphs. |
141+ | - Bar | 1. Bar |
142+ | - Line | 2. Line |
143+ | - Pie | 3. Pie |
144+ +------------------------------------+------------------------------------+
145+ | These three steps help to get | The following steps are important |
146+ | started using Matplotlib. | to get started using Matplotlib. |
147+ | 1. Import the Matplotlib library. | - Import the Matplotlib library. |
148+ | 2. Import the necessary modules. | - Import the necessary modules. |
149+ | 3. Set and assign data to work on. | - Set and assign data to work on. |
150+ | 4. Transform data with methods and | - Transform data with methods and |
151+ | functions. | functions. |
90152+------------------------------------+------------------------------------+
91153
92154Additional Resources
93155====================
94156
95157* `Red Hat Style Guide <https://stylepedia.net/style/#grammar >`_
96158* `IBM Style Guide <https://www.ibm.com/developerworks/library/styleguidelines/ >`_
97- * `Google Developer Style Guide <https://developers.google.com/style >`_
159+ * `Google Developer Style Guide <https://developers.google.com/style >`_
160+
161+ +------------------------------------+------------------------------------+
162+ | Correct | Incorrect |
163+ +------------------------------------+------------------------------------+
164+ | | |
165+ +------------------------------------+------------------------------------+
0 commit comments