Merge pull request #26754 from story645/axisartist-table

QuLogic · web-flow · commit cfe5bf75eaf3 · 2023-10-07T03:17:03.000-04:00
DOC: seperate and clarify axisartist default tables
diff --git a/doc/devel/document.rst b/doc/devel/document.rst
@@ -142,7 +142,7 @@ It is useful to strive for consistency in the Matplotlib documentation.  Here
 are some formatting and style conventions that are used.
 
 Section formatting
-~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^
 
 Use `sentence case <https://apastyle.apa.org/style-grammar-guidelines/capitalization/sentence-case>`__
 ``Upper lower`` for section titles, e.g., ``Possible hangups`` rather than
@@ -163,8 +163,25 @@ for section markup characters, i.e.:
 
 This may not yet be applied consistently in existing docs.
 
+Table formatting
+^^^^^^^^^^^^^^^^
+Given the size of the table and length of each entry, use:
+
++-------------+-------------------------------+--------------------+
+|             | small table                   | large table        |
++-------------+-------------------------------+--------------------+
+| short entry | `simple or grid table <sg>`_  | `grid table <sg>`_ |
++-------------+-------------------------------+--------------------+
+| long entry  | `list table <lt>`_            | `csv table <csv>`_ |
++-------------+-------------------------------+--------------------+
+
+For more information, see `rst tables <https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#tables>`_.
+.. _sg: https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#tables
+.. _lt: https://docutils.sourceforge.io/docs/ref/rst/directives.html#list-table
+.. _csv: https://docutils.sourceforge.io/docs/ref/rst/directives.html#toc-entry-22
+
 Function arguments
-~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^
 
 Function arguments and keywords within docstrings should be referred to using
 the ``*emphasis*`` role. This will keep Matplotlib's documentation consistent
@@ -445,7 +462,8 @@ and the Sphinx_ documentation.  Some Matplotlib-specific formatting conventions
 to keep in mind:
 
 Quote positions
-~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^
+
 The quotes for single line docstrings are on the same line (pydocstyle D200)::
 
     def get_linewidth(self):
@@ -461,7 +479,8 @@ The quotes for multi-line docstrings are on separate lines (pydocstyle D213)::
         """
 
 Function arguments
-~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^
+
 Function arguments and keywords within docstrings should be referred to
 using the ``*emphasis*`` role. This will keep Matplotlib's documentation
 consistent with Python's documentation:
@@ -478,7 +497,8 @@ Do not use the ```default role``` or the ````literal```` role:
 
 
 Quotes for strings
-~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^
+
 Matplotlib does not have a convention whether to use single-quotes or
 double-quotes.  There is a mixture of both in the current code.
 
@@ -495,7 +515,8 @@ slightly improve the rendered docs, they are cumbersome to type and difficult
 to read in plain-text docs.
 
 Parameter type descriptions
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
 The main goal for parameter type descriptions is to be readable and
 understandable by humans. If the possible types are too complex use a
 simplification for the type description and explain the type more
@@ -534,7 +555,8 @@ Non-numeric homogeneous sequences are described as lists, e.g.::
   list of `.Artist`
 
 Reference types
-~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^
+
 Generally, the rules from referring-to-other-code_ apply. More specifically:
 
 Use full references ```~matplotlib.colors.Normalize``` with an
@@ -550,7 +572,8 @@ Use abbreviated links ```.Normalize``` in the text.
         A `.Normalize` instance is used to scale luminance data to 0, 1.
 
 Default values
-~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^
+
 As opposed to the numpydoc guide, parameters need not be marked as
 *optional* if they have a simple default:
 
@@ -592,7 +615,8 @@ effect.
 
 
 ``See also`` sections
-~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^
+
 Sphinx automatically links code elements in the definition blocks of ``See
 also`` sections. No need to use backticks there::
 
@@ -602,7 +626,8 @@ also`` sections. No need to use backticks there::
    axhline : horizontal line across the Axes
 
 Wrap parameter lists
-~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^
+
 Long parameter lists should be wrapped using a ``\`` for continuation and
 starting on the new line without any indent (no indent because pydoc will
 parse the docstring and strip the line continuation so that indent would
@@ -627,7 +652,8 @@ Alternatively, you can describe the valid parameter values in a dedicated
 section of the docstring.
 
 rcParams
-~~~~~~~~
+^^^^^^^^
+
 rcParams can be referenced with the custom ``:rc:`` role:
 :literal:`:rc:\`foo\`` yields ``rcParams["foo"] = 'default'``, which is a link
 to the :file:`matplotlibrc` file description.
diff --git a/galleries/users_explain/toolkits/axisartist.rst b/galleries/users_explain/toolkits/axisartist.rst
@@ -341,18 +341,37 @@ On the other hand, there is a concept of "axis_direction". This is a
 default setting of above properties for each, "bottom", "left", "top",
 and "right" axis.
 
-========== ========== ========= ========== ========= ==========
-label type  parameter    left      bottom      right      top
-========== ========== ========= ========== ========= ==========
-axislabel   direction      '-'       '+'        '+'      '-'
-axislabel   rotation      180         0          0       180
-axislabel   va           center    top       center     bottom
-axislabel   ha           right    center      right     center
-ticklabel   direction      '-'       '+'        '+'      '-'
-ticklabel   rotation       90         0        -90       180
-ticklabel   ha           right    center      right     center
-ticklabel   va           center   baseline    center   baseline
-========== ========== ========= ========== ========= ==========
+.. table:: ``axislabel`` property defaults
+
+   +---------------------+-----------------+----------------+----------------------+--------------------+
+   | reference direction | label direction | label rotation | horizontal alignment | vertical alignment |
+   +=====================+=================+================+======================+====================+
+   | left                | '-'             | 180            | right                | center             |
+   +---------------------+-----------------+----------------+----------------------+--------------------+
+   | bottom              | '+'             | 0              | center               | top                |
+   +---------------------+-----------------+----------------+----------------------+--------------------+
+   | right               | '+'             | 0              | right                | center             |
+   +---------------------+-----------------+----------------+----------------------+--------------------+
+   | top                 | '-'             | 180            | center               | bottom             |
+   +---------------------+-----------------+----------------+----------------------+--------------------+
+
+
+
+.. table:: ``ticklabel`` property defaults
+
+   +---------------------+-----------------+----------------+----------------------+--------------------+
+   | reference direction | label direction | label rotation | horizontal alignment | vertical alignment |
+   +=====================+=================+================+======================+====================+
+   | left                | '-'             | 90             | right                | center             |
+   +---------------------+-----------------+----------------+----------------------+--------------------+
+   | bottom              | '+'             | 0              | center               | baseline           |
+   +---------------------+-----------------+----------------+----------------------+--------------------+
+   | right               | '+'             | -90            | right                | center             |
+   +---------------------+-----------------+----------------+----------------------+--------------------+
+   | top                 | '-'             | 180            | center               | baseline           |
+   +---------------------+-----------------+----------------+----------------------+--------------------+
+
+
 
 And, 'set_axis_direction("top")' means to adjust the text rotation
 etc, for settings suitable for "top" axis. The concept of axis
