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

Skip to content

DOC: separate and clarify axisartist default tables #26754

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Oct 7, 2023
Merged

DOC: separate and clarify axisartist default tables #26754

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
52d87ca
separate and clarify axisartist default tables
story645 Sep 12, 2023
be1c941
document table usage and clean up headings
story645 Oct 6, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
48 changes: 37 additions & 11 deletions doc/devel/document.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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):
Expand All @@ -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:
Expand All @@ -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.

Expand All @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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:

Expand Down Expand Up @@ -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::

Expand All @@ -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
Expand All @@ -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.
Expand Down
43 changes: 31 additions & 12 deletions galleries/users_explain/toolkits/axisartist.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down