diff --git a/doc/devel/document.rst b/doc/devel/document.rst index ac92888b4052..095b42d689ce 100644 --- 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 `__ ``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 `_ | `grid table `_ | ++-------------+-------------------------------+--------------------+ +| long entry | `list table `_ | `csv table `_ | ++-------------+-------------------------------+--------------------+ + +For more information, see `rst 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 index 313a0fb5a9e9..4927f9a3c940 100644 --- 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