Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit bfccdaf

Browse files
jeromefvjeromefv
committed
style_guide & getting_started modifications
links in tables, proofreading, supplemental section, 2nd person subject
1 parent 85b6a13 commit bfccdaf

File tree

2 files changed

+65
-31
lines changed

2 files changed

+65
-31
lines changed

‎doc/devel/style_guide.rst

Lines changed: 31 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -16,27 +16,30 @@ Terminology
1616
-----------
1717

1818
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.
19+
reliability and consistency in documentation. They are case-sensitive and are
20+
not interchangeable.
2121

2222
+------------------+--------------------------+--------------+--------------+
2323
| Term | Description | Correct | Incorrect |
2424
+==================+==========================+==============+==============+
25-
| Figure | Matplotlib working space |- One Figure |- One figure |
25+
| Figure_ | Matplotlib working space |- One Figure |- One figure |
2626
| | for programming. |- 11 Figures |- 11 figures |
2727
+------------------+--------------------------+--------------+--------------+
28-
| Axes | Subplots within Figure. | - One Axes | - One axes |
28+
| Axes_ | Subplots within Figure. | - One Axes | - One axes |
2929
| | Contains Figure elements | - Four Axes | - Four Axeses|
3030
| | and is responsible for | - 32 Axes | - 32 Axii |
3131
| | plotting and configuring | | |
3232
| | additional details. | | |
3333
+------------------+--------------------------+--------------+--------------+
34-
| Artist | Broad Matplotlib object | - One Artist | - One artist |
34+
| Artist_ | Broad Matplotlib object | - One Artist | - One artist |
3535
| | that displays visuals. | - Two Artists| - Two artists|
3636
+------------------+--------------------------+--------------+--------------+
37-
| Axis | Refers to visible object | - One Axis | - One axis |
38-
| | corresponding to labeling| - Four Axis | - Four Axises|
39-
| | of plotted data. | objects | - 32 Axes |
37+
| Axis_ | Human-readable single | - One Axis | - One Axis |
38+
| | dimensional object | object | - One axis |
39+
| | of reference marks | - Four Axis | - Four Axises|
40+
| | containing ticks, tick | objects | - 32 Axes |
41+
| | labels, spines, and | - 32 Axis | |
42+
| | edges. | objects | |
4043
+------------------+--------------------------+--------------+--------------+
4144
| Explicit, | Explicit approach of | - Explicit | - object |
4245
| Object Oriented | programing in Matplotlib.| - explicit | oriented |
@@ -48,26 +51,29 @@ are not interchangeable.
4851
| | | | interface |
4952
+------------------+--------------------------+--------------+--------------+
5053

54+
.. _Figure: :class:`~matplotlib.figure.Figure`
55+
.. _Axes: :class:`~matplotlib.axes.Axes`
56+
.. _Artist: :class:`~matplotlib.artist.Artist`
57+
.. _Axis: :class:`matplotlib.axis.Axis`
58+
5159

5260
Grammar
5361
-------
5462

5563
Subject
5664
^^^^^^^
57-
The audience is the "user" in the documentation. A "user" is a person
58-
programming in Python with the Matplotlib library.
59-
60-
Use second-person sentences for instructions directed at user for specifying
61-
an action or a possessive reference.
65+
Use second-person imperative sentences for directed instructions specifying an
66+
action. Second-person pronouns are for individual-specific contexts and
67+
possessive reference.
6268

6369
+------------------------------------+------------------------------------+
6470
| Correct | Incorrect |
6571
+====================================+====================================+
66-
| Users install Matplotlib from the | You can install Matplotlib from the|
67-
| source directory using the Python | source directory. You can find |
68-
| ``pip`` installer program. | additional support if you are |
69-
| Depending on your operating system,| having troulbe with your |
70-
| you may need additional support. | installation. |
72+
| Install Matplotlib from the source | You can install Matplotlib from the|
73+
| directory using the Python ``pip`` | source directory. You can find |
74+
| installer program. Depending on | additional support if you are |
75+
| your operating system, you may need| having trouble with your |
76+
| additional support. | installation. |
7177
+------------------------------------+------------------------------------+
7278

7379
Tense
@@ -105,7 +111,7 @@ Sentence structure
105111
^^^^^^^^^^^^^^^^^^
106112
Write with short sentences using Subject-Verb-Object order regularly. Limit
107113
how frequently coordinating conjunctions appear in sentences. Avoid pronoun
108-
referenes and subordinating conjunctive prhases.
114+
references and subordinating conjunctive phrases.
109115

110116
+------------------------------------+------------------------------------+
111117
| Correct | Incorrect |
@@ -136,14 +142,14 @@ visibility.
136142

137143
reStructuredText standards
138144
--------------------------
139-
- https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html
140-
- https://docutils.sourceforge.io/docs/user/rst/quickref.html
145+
- `reStructuredText Specifications <https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html>`_
146+
- `Quick Reference Document <https://docutils.sourceforge.io/docs/user/rst/quickref.html>`_
141147

142148

143149
Lists
144150
^^^^^
145-
Bulleted lists are for items that do not require sequencing.
146-
Numbered Lists are exclusively for performing actions in specific order.
151+
Bulleted lists are for items that do not require sequencing. Numbered lists are
152+
exclusively for performing actions in a determined order.
147153

148154
+------------------------------------+------------------------------------+
149155
| Correct | Incorrect |
@@ -167,7 +173,7 @@ Numbered Lists are exclusively for performing actions in specific order.
167173
Additional Resources
168174
====================
169175

170-
* `Red Hat Style Guide <https://stylepedia.net/style/#grammar>`_
171-
* `IBM Style Guide <https://www.ibm.com/developerworks/library/styleguidelines/>`_
172176
* `Google Developer Style Guide <https://developers.google.com/style>`_
177+
* `IBM Style Guide <https://www.ibm.com/developerworks/library/styleguidelines/>`_
178+
* `Red Hat Style Guide <https://stylepedia.net/style/#grammar>`_
173179

‎tutorials/introductory/getting_started.py

Lines changed: 34 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -369,6 +369,10 @@
369369
# contain multiple types of visualizations of data on a single Axes. Each of
370370
# these types are specific to the Axes they are in.
371371
#
372+
# Matplotlib Axes also intergrate with other Python libraries. In Axes-based
373+
# interfaces, other libraries take an Axes object as input. Libraries such as
374+
# `pandas` and `Seaborn <https://seaborn.pydata.org>`_ act on specific Axes.
375+
#
372376
# Other Components
373377
# ^^^^^^^^^^^^^^^^
374378
#
@@ -438,7 +442,32 @@
438442
# | Legend (Axes) | ``ax.legend()`` | ``plt.legend()`` |
439443
# +-----------------------+--------------------------+------------------------+
440444
#
441-
# For complete information about available methods, refer to the table below.
445+
# Supplemental Resources
446+
# ^^^^^^^^^^^^^^^^^^^^^^
447+
#
448+
# Customizations with robust options have their own guides and tutorials. The
449+
# topics below include common in-depth documents for additional support.
450+
#
451+
# +------------------------------+--------------------------------------------+
452+
# | Topic | Tutorial |
453+
# +==============================+============================================+
454+
# | :ref:`tutorials-introductory`| :doc:`/tutorials/introductory/customizing` |
455+
# +------------------------------+--------------------------------------------+
456+
# | :ref:`tutorials-intermediate`| :doc:`/tutorials/intermediate/legend_guide`|
457+
# +------------------------------+--------------------------------------------+
458+
# | :ref:`tutorials-colors` | :doc:`/tutorials/colors/colors` |
459+
# | +--------------------------------------------+
460+
# | | :doc:`/tutorials/colors/colormaps` |
461+
# +------------------------------+--------------------------------------------+
462+
# | :ref:`tutorials-text` | :doc:`/tutorials/text/text_intro` |
463+
# | +--------------------------------------------+
464+
# | | :doc:`/tutorials/text/text_props` |
465+
# | +--------------------------------------------+
466+
# | | :doc:`/tutorials/text/annotations` |
467+
# +------------------------------+--------------------------------------------+
468+
#
469+
# For complete information about available methods for Artists, refer to the
470+
# table below.
442471
#
443472
# +------------------------------------+------------------------------------+
444473
# | Explicit | Implicit |
@@ -592,8 +621,7 @@ def autopct_format(percent, group):
592621
# The following pie chart has additional keyword arguments to further
593622
# customize the visual. Also, the ``legend`` as an Artist has parameters that
594623
# enable more specification for the information displayed. For more, see the
595-
# `Legend Guide
596-
# <https://matplotlib.org/tutorials/intermediate/legend_guide.html?highlight=legend%20guide>`_.
624+
# :doc:`/tutorials/intermediate/legend_guide`.
597625

598626
# Explicit
599627

@@ -743,10 +771,10 @@ def autopct_format(percent, group):
743771
#
744772
# fig, ax = plt.subplots(2,2)
745773
#
746-
# ax[0,0].plot([1,2,3],[1,2,3])
774+
# ax[0,0].bar([1,2,3],[1,2,3])
747775
# ax[0,1].plot([3,2,1],[3,2,1])
748-
# ax[1,0].plot([3,2,1],[3,2,1])
749-
# ax[1,1].plot([1,2,3],[1,2,3])
776+
# ax[1,0].hist(hist_data)
777+
# ax[1,1].imshow([[1,2], [2,1]])
750778
#
751779
#
752780
# The method `matplotlib.figure.Figure.subplot_mosaic` also generates Axes in

0 commit comments

Comments
 (0)