From 88e8d2ae77d20abfc1a30cef6033a937577c7246 Mon Sep 17 00:00:00 2001 From: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com> Date: Sun, 16 May 2021 02:30:07 +0200 Subject: [PATCH] Style tables in style guide: - Widths in terminology table - Comparison tables: 100% total width, 50% per column Note: We need to use the `.. table::` directive explicitly to manipulate the widths that are written in to `` by ReST. CSS alone cannot override these. --- doc/devel/style_guide.rst | 541 ++++++++++++++++++++------------------ 1 file changed, 288 insertions(+), 253 deletions(-) diff --git a/doc/devel/style_guide.rst b/doc/devel/style_guide.rst index 957cd76ed685..62e84dc9d1fa 100644 --- a/doc/devel/style_guide.rst +++ b/doc/devel/style_guide.rst @@ -23,141 +23,144 @@ 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 | - "The figure| -| | for programming. | Matplotlib | is the | -| | | objects*: | working | -| | | Figure, | space for | -| | | "The Figure| visuals." | -| | | is the | - "Methods in| -| | | working | the figure | -| | | space for | provide the| -| | | the visual.| visuals." | -| | | - *Referring | - "The | -| | | to class*: | Figure_ | -| | | Figure_ , | Four | -| | | "Methods | leglock is | -| | | within the | a wrestling| -| | | Figure_ | move." | -| | | provide the| | -| | | visuals." | | -| | | - *General | | -| | | language*: | | -| | | figure, | | -| | | "Michelle | | -| | | Kwan is a | | -| | | famous | | -| | | figure | | -| | | skater." | | -+------------------+--------------------------+--------------+--------------+ -| Axes_ | Subplots within Figure. | - *For | - "The axes | -| | Contains plot elements | Matplotlib | methods | -| | and is responsible for | objects*: | transform | -| | plotting and configuring | Axes, "An | the data." | -| | additional details. | Axes is a | - "Each Axes_| -| | | subplot | is specific| -| | | within the | to a | -| | | Figure." | Figure." | -| | | - *Referring | - "The | -| | | to class*: | musicians | -| | | Axes_ , | on stage | -| | | "Each Axes_| call their | -| | | is specific| guitars | -| | | to one | Axes." | -| | | Figure." | - "The point | -| | | - *General | where the | -| | | language*: | Axes meet | -| | | axes, "Both| is the | -| | | loggers and| origin of | -| | | lumberjacks| the | -| | | use axes to| coordinate | -| | | chop wood."| system." | -| | | OR "There | | -| | | are no | | -| | | standard | | -| | | names for | | -| | | the | | -| | | coordinates| | -| | | in the | | -| | | three | | -| | | axes." | | -| | | (Plural of | | -| | | axis) | | -+------------------+--------------------------+--------------+--------------+ -| Artist_ | Broad variety of | - *For | - "Configure | -| | Matplotlib objects that | Matplotlib | the legend | -| | display visuals. | objects*: | artist with| -| | | Artist, | its | -| | | "Artists | respective | -| | | display | method." | -| | | visuals and| - "There is | -| | | are the | an Artist_ | -| | | visible | for that | -| | | elements | visual in | -| | | when the | the graph."| -| | | rendering | - "Some | -| | | a Figure." | Artists | -| | | - *Referring | became | -| | | to class*: | famous only| -| | | Artist_ , | by | -| | | "Each | accident." | -| | | Artist_ has| | -| | | respective | | -| | | methods and| | -| | | functions."| | -| | | - *General | | -| | | language*: | | -| | | artist, | | -| | | "The | | -| | | artist in | | -| | | the museum | | -| | | is from | | -| | | France." | | -+------------------+--------------------------+--------------+--------------+ -| Axis_ | Human-readable single | - *For | - "Plot the | -| | dimensional object | Matplotlib | graph onto | -| | of reference marks | objects*: | the axis." | -| | containing ticks, tick | Axis, "The | - "Each Axis | -| | labels, spines, and | Axis for | is usually | -| | edges. | the bar | named after| -| | | chart is a | the | -| | | separate | coordinate | -| | | Artist." | which is | -| | | (plural, | measured | -| | | Axis | along it." | -| | | objects) | - "In some | -| | | - *Referring | computer | -| | | to class*: | graphics | -| | | Axis_ , | contexts, | -| | | "The Axis_ | the | -| | | contains | ordinate | -| | | respective | Axis_ may | -| | | XAxis and | be oriented| -| | | YAxis | downwards."| -| | | objects." | | -| | | - *General | | -| | | language*: | | -| | | axis, | | -| | | "Rotation | | -| | | around a | | -| | | fixed axis | | -| | | is a | | -| | | special | | -| | | case of | | -| | | rotational | | -| | | motion." | | -+------------------+--------------------------+--------------+--------------+ -| Explicit, | Explicit approach of | - Explicit | - object | -| Object Oriented | programing in Matplotlib.| - explicit | oriented | -| Programming (OOP)| | - OOP | - OO-style | -+------------------+--------------------------+--------------+--------------+ -| Implicit, | Implicit approach of | - Implicit | - MATLAB like| -| ``pyplot`` | programming in Matplotlib| - implicit | - Pyplot | -| | with ``pyplot`` module. | - ``pyplot`` | - pyplot | -| | | | interface | -+------------------+--------------------------+--------------+--------------+ +.. table:: + :widths: 15, 15, 35, 35 + + +------------------+--------------------------+--------------+--------------+ + | Term | Description | Correct | Incorrect | + +==================+==========================+==============+==============+ + | Figure_ | Matplotlib working space | - *For | - "The figure| + | | for programming. | Matplotlib | is the | + | | | objects*: | working | + | | | Figure, | space for | + | | | "The Figure| visuals." | + | | | is the | - "Methods in| + | | | working | the figure | + | | | space for | provide the| + | | | the visual.| visuals." | + | | | - *Referring | - "The | + | | | to class*: | Figure_ | + | | | Figure_ , | Four | + | | | "Methods | leglock is | + | | | within the | a wrestling| + | | | Figure_ | move." | + | | | provide the| | + | | | visuals." | | + | | | - *General | | + | | | language*: | | + | | | figure, | | + | | | "Michelle | | + | | | Kwan is a | | + | | | famous | | + | | | figure | | + | | | skater." | | + +------------------+--------------------------+--------------+--------------+ + | Axes_ | Subplots within Figure. | - *For | - "The axes | + | | Contains plot elements | Matplotlib | methods | + | | and is responsible for | objects*: | transform | + | | plotting and configuring | Axes, "An | the data." | + | | additional details. | Axes is a | - "Each Axes_| + | | | subplot | is specific| + | | | within the | to a | + | | | Figure." | Figure." | + | | | - *Referring | - "The | + | | | to class*: | musicians | + | | | Axes_ , | on stage | + | | | "Each Axes_| call their | + | | | is specific| guitars | + | | | to one | Axes." | + | | | Figure." | - "The point | + | | | - *General | where the | + | | | language*: | Axes meet | + | | | axes, "Both| is the | + | | | loggers and| origin of | + | | | lumberjacks| the | + | | | use axes to| coordinate | + | | | chop wood."| system." | + | | | OR "There | | + | | | are no | | + | | | standard | | + | | | names for | | + | | | the | | + | | | coordinates| | + | | | in the | | + | | | three | | + | | | axes." | | + | | | (Plural of | | + | | | axis) | | + +------------------+--------------------------+--------------+--------------+ + | Artist_ | Broad variety of | - *For | - "Configure | + | | Matplotlib objects that | Matplotlib | the legend | + | | display visuals. | objects*: | artist with| + | | | Artist, | its | + | | | "Artists | respective | + | | | display | method." | + | | | visuals and| - "There is | + | | | are the | an Artist_ | + | | | visible | for that | + | | | elements | visual in | + | | | when the | the graph."| + | | | rendering | - "Some | + | | | a Figure." | Artists | + | | | - *Referring | became | + | | | to class*: | famous only| + | | | Artist_ , | by | + | | | "Each | accident." | + | | | Artist_ has| | + | | | respective | | + | | | methods and| | + | | | functions."| | + | | | - *General | | + | | | language*: | | + | | | artist, | | + | | | "The | | + | | | artist in | | + | | | the museum | | + | | | is from | | + | | | France." | | + +------------------+--------------------------+--------------+--------------+ + | Axis_ | Human-readable single | - *For | - "Plot the | + | | dimensional object | Matplotlib | graph onto | + | | of reference marks | objects*: | the axis." | + | | containing ticks, tick | Axis, "The | - "Each Axis | + | | labels, spines, and | Axis for | is usually | + | | edges. | the bar | named after| + | | | chart is a | the | + | | | separate | coordinate | + | | | Artist." | which is | + | | | (plural, | measured | + | | | Axis | along it." | + | | | objects) | - "In some | + | | | - *Referring | computer | + | | | to class*: | graphics | + | | | Axis_ , | contexts, | + | | | "The Axis_ | the | + | | | contains | ordinate | + | | | respective | Axis_ may | + | | | XAxis and | be oriented| + | | | YAxis | downwards."| + | | | objects." | | + | | | - *General | | + | | | language*: | | + | | | axis, | | + | | | "Rotation | | + | | | around a | | + | | | fixed axis | | + | | | is a | | + | | | special | | + | | | case of | | + | | | rotational | | + | | | motion." | | + +------------------+--------------------------+--------------+--------------+ + | Explicit, | Explicit approach of | - Explicit | - object | + | Object Oriented | programing in Matplotlib.| - explicit | oriented | + | Programming (OOP)| | - OOP | - OO-style | + +------------------+--------------------------+--------------+--------------+ + | Implicit, | Implicit approach of | - Implicit | - MATLAB like| + | ``pyplot`` | programming in Matplotlib| - implicit | - Pyplot | + | | with ``pyplot`` module. | - ``pyplot`` | - pyplot | + | | | | interface | + +------------------+--------------------------+--------------+--------------+ .. _Figure: :class:`~matplotlib.figure.Figure` .. _Axes: :class:`~matplotlib.axes.Axes` @@ -174,46 +177,58 @@ 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 | You can install Matplotlib from the| -| directory using the Python ``pip`` | source directory. You can find | -| installer program. Depending on | additional support if you are | -| your operating system, you may need| having trouble with your | -| additional support. | installation. | -+------------------------------------+------------------------------------+ +.. table:: + :width: 100% + :widths: 50, 50 + + +------------------------------------+------------------------------------+ + | Correct | Incorrect | + +====================================+====================================+ + | Install Matplotlib from the source | You can install Matplotlib from the| + | directory using the Python ``pip`` | source directory. You can find | + | installer program. Depending on | additional support if you are | + | your operating system, you may need| having trouble with your | + | additional support. | 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 will take data and | -| Matplotlib for visualization | transform it through functions and | -| involve taking data and | methods. They can generate many | -| transforming it through functions | kinds of visuals. These will be the| -| and methods. | fundamentals for using Matplotlib. | -+------------------------------------+------------------------------------+ +.. table:: + :width: 100% + :widths: 50, 50 + + +------------------------------------+------------------------------------+ + | Correct | Incorrect | + +====================================+====================================+ + | The fundamental ideas behind | Matplotlib will take data and | + | Matplotlib for visualization | transform it through functions and | + | involve taking data and | methods. They can generate many | + | transforming it through functions | kinds of visuals. These will be the| + | and methods. | 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| The graph is generated by the | -| graph. | ``plot`` function. | -+------------------------------------+------------------------------------+ -| An error message is returned by the| You will see an error message from | -| function if there are no arguments.| the function if there are no | -| | arguments. | -+------------------------------------+------------------------------------+ +.. table:: + :width: 100% + :widths: 50, 50 + + +------------------------------------+------------------------------------+ + | Correct | Incorrect | + +====================================+====================================+ + | The function ``plot`` generates the| The graph is generated by the | + | graph. | ``plot`` function. | + +------------------------------------+------------------------------------+ + | An error message is returned by the| You will see an error message from | + | function if there are no arguments.| the function if there are no | + | | arguments. | + +------------------------------------+------------------------------------+ Sentence structure ^^^^^^^^^^^^^^^^^^ @@ -221,24 +236,28 @@ 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| The ``pyplot`` module in Matplotlib| -| is a collection of functions. These| is a collection of functions which | -| functions create, manage, and | create, manage, and manipulate the | -| manipulate the current Figure and | current Figure and plotting area. | -| plotting area. | | -+------------------------------------+------------------------------------+ -| The ``plot`` function plots data | The ``plot`` function plots data | -| to the respective Axes. The Axes | within its respective Axes for its | -| corresponds to the respective | respective Figure. | -| Figure. | | -+------------------------------------+------------------------------------+ -| The implicit approach is a | Users that wish to have convenient | -| convenient shortcut for | shortcuts for generating plots use | -| generating simple plots. | the implicit approach. | -+------------------------------------+------------------------------------+ +.. table:: + :width: 100% + :widths: 50, 50 + + +------------------------------------+------------------------------------+ + | Correct | Incorrect | + +====================================+====================================+ + | The ``pyplot`` module in Matplotlib| The ``pyplot`` module in Matplotlib| + | is a collection of functions. These| is a collection of functions which | + | functions create, manage, and | create, manage, and manipulate the | + | manipulate the current Figure and | current Figure and plotting area. | + | plotting area. | | + +------------------------------------+------------------------------------+ + | The ``plot`` function plots data | The ``plot`` function plots data | + | to the respective Axes. The Axes | within its respective Axes for its | + | corresponds to the respective | respective Figure. | + | Figure. | | + +------------------------------------+------------------------------------+ + | The implicit approach is a | Users that wish to have convenient | + | convenient shortcut for | shortcuts for generating plots use | + | generating simple plots. | the implicit approach. | + +------------------------------------+------------------------------------+ Formatting @@ -257,18 +276,22 @@ 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 | | -+---------------------------------------+---------------------------------+ +.. table:: + :width: 100% + :widths: 50, 50 + + +---------------------------------------+---------------------------------+ + | Correct | Incorrect | + +=======================================+=================================+ + | :: | :: | + | | | + | # Data | years = [2006, 2007, 2008] | + | years = [2006, 2007, 2008] | # Data | + +---------------------------------------+ | + | :: | | + | | | + | years = [2006, 2007, 2008] # Data | | + +---------------------------------------+---------------------------------+ Outputs ^^^^^^^ @@ -276,20 +299,24 @@ 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.plot([1, 2, 3], [1, 2, 3]) | -| plt.show() | | -+------------------------------------+------------------------------------+ -| :: | :: | -| | | -| fig, ax = plt.subplots() | fig, ax = plt.subplots() | -| ax.plot([1, 2, 3], [1, 2, 3]) | ax.plot([1, 2, 3], [1, 2, 3]) | -| fig.show() | | -+------------------------------------+------------------------------------+ +.. table:: + :width: 100% + :widths: 50, 50 + + +------------------------------------+------------------------------------+ + | Correct | Incorrect | + +====================================+====================================+ + | :: | :: | + | | | + | plt.plot([1, 2, 3], [1, 2, 3]) | plt.plot([1, 2, 3], [1, 2, 3]) | + | plt.show() | | + +------------------------------------+------------------------------------+ + | :: | :: | + | | | + | fig, ax = plt.subplots() | fig, ax = plt.subplots() | + | ax.plot([1, 2, 3], [1, 2, 3]) | ax.plot([1, 2, 3], [1, 2, 3]) | + | fig.show() | | + +------------------------------------+------------------------------------+ reStructuredText ---------------- @@ -307,58 +334,66 @@ 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 | 1. Bar | -| - Line | 2. Line | -| - Pie | 3. Pie | -+------------------------------------+------------------------------------+ -| These four steps help to get | The following steps are important | -| started using Matplotlib. | to get started using Matplotlib. | -+------------------------------------+------------------------------------+ -| 1. Import the Matplotlib library. | - Import the Matplotlib library. | -| 2. Import the necessary modules. | - Import the necessary modules. | -| 3. Set and assign data to work on.| - Set and assign data to work on. | -| 4. Transform data with methods and| - Transform data with methods and | -| functions. | functions. | -+------------------------------------+------------------------------------+ +.. table:: + :width: 100% + :widths: 50, 50 + + +------------------------------------+------------------------------------+ + | Correct | Incorrect | + +====================================+====================================+ + | The example uses three graphs. | The example uses three graphs. | + +------------------------------------+------------------------------------+ + | - Bar | 1. Bar | + | - Line | 2. Line | + | - Pie | 3. Pie | + +------------------------------------+------------------------------------+ + | These four steps help to get | The following steps are important | + | started using Matplotlib. | to get started using Matplotlib. | + +------------------------------------+------------------------------------+ + | 1. Import the Matplotlib library. | - Import the Matplotlib library. | + | 2. Import the necessary modules. | - Import the necessary modules. | + | 3. Set and assign data to work on.| - Set and assign data to work on. | + | 4. Transform data with methods and| - Transform data with methods and | + | functions. | 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| | | -| +==========+==========+ | | Correct | Incorrect | | -| | OK | Not OK | | | ------- | --------- | | -| +----------+----------+ | | OK | Not OK | | -| | | -+--------------------------------+----------------------------------------+ -| :: | :: | -| | | -| +----------+----------+ | .. csv-table:: | -| | Correct | Incorrect| | :header: "correct", "incorrect" | -| +==========+==========+ | :widths: 10, 10 | -| | OK | Not OK | | | -| +----------+----------+ | "OK ", "Not OK" | -| | | -+--------------------------------+ | -| :: | | -| | | -| =========== =========== | | -| Correct Incorrect | | -| =========== =========== | | -| OK Not OK | | -| =========== =========== | | -| | | -+--------------------------------+----------------------------------------+ +.. table:: + :width: 100% + :widths: 50, 50 + + +--------------------------------+----------------------------------------+ + | Correct | Incorrect | + +================================+========================================+ + | +----------+----------+ | :: | + | | Correct | Incorrect| | | + | +==========+==========+ | | Correct | Incorrect | | + | | OK | Not OK | | | ------- | --------- | | + | +----------+----------+ | | OK | Not OK | | + | | | + +--------------------------------+----------------------------------------+ + | :: | :: | + | | | + | +----------+----------+ | .. csv-table:: | + | | Correct | Incorrect| | :header: "correct", "incorrect" | + | +==========+==========+ | :widths: 10, 10 | + | | OK | Not OK | | | + | +----------+----------+ | "OK ", "Not OK" | + | | | + +--------------------------------+ | + | :: | | + | | | + | =========== =========== | | + | Correct Incorrect | | + | =========== =========== | | + | OK Not OK | | + | =========== =========== | | + | | | + +--------------------------------+----------------------------------------+ Additional resources