From 18b95257b669f75082f131835679c1a3643ddb4a Mon Sep 17 00:00:00 2001 From: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com> Date: Mon, 9 Jul 2018 21:47:06 +0200 Subject: [PATCH] Fix css for parameter types --- doc/_static/mpl.css | 4 - doc/devel/documenting_mpl.rst | 161 ++++++++++++++++++---------------- 2 files changed, 84 insertions(+), 81 deletions(-) diff --git a/doc/_static/mpl.css b/doc/_static/mpl.css index af7ab4a1bc1b..93a7f84518f9 100644 --- a/doc/_static/mpl.css +++ b/doc/_static/mpl.css @@ -147,10 +147,6 @@ dl.glossary dt { font-size: 1.1em; } -dl.docutils dt { - font-weight: bold; -} - pre a { color: inherit; text-decoration: none; diff --git a/doc/devel/documenting_mpl.rst b/doc/devel/documenting_mpl.rst index acef194ed9d0..42f5bd89cb88 100644 --- a/doc/devel/documenting_mpl.rst +++ b/doc/devel/documenting_mpl.rst @@ -5,7 +5,7 @@ Writing documentation ===================== .. contents:: Contents - :depth: 2 + :depth: 3 :local: :backlinks: top :class: multicol-toc @@ -387,123 +387,130 @@ and the Sphinx_ documentation. Some Matplotlib-specific formatting conventions to keep in mind: 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: +~~~~~~~~~~~~~~~~~~ +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: - .. code-block:: rst +.. code-block:: rst - If *linestyles* is *None*, the 'solid' is used. + If *linestyles* is *None*, the 'solid' is used. - Do not use the ```default role``` or the ````literal```` role: +Do not use the ```default role``` or the ````literal```` role: - .. code-block:: rst +.. code-block:: rst - Neither `argument` nor ``argument`` should be used. + Neither `argument` nor ``argument`` should be used. 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. +~~~~~~~~~~~~~~~~~~ +Matplotlib does not have a convention whether to use single-quotes or +double-quotes. There is a mixture of both in the current code. - Use simple single or double quotes when giving string values, e.g.:: rst +Use simple single or double quotes when giving string values, e.g.:: rst - .. code-block:: rst +.. code-block:: rst - If 'tight', try to figure out the tight bbox of the figure. + If 'tight', try to figure out the tight bbox of the figure. 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 - precisely in the text. +~~~~~~~~~~~~~~~~~~~~~~~~~~~ +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 +precisely in the text. - Generally, the `numpydoc docstring guide`_ conventions apply. The following - rules expand on them where the numpydoc conventions are not specific. +Generally, the `numpydoc docstring guide`_ conventions apply. The following +rules expand on them where the numpydoc conventions are not specific. - Use ``float`` for a type that can be any number. +Use ``float`` for a type that can be any number. - Use ``array-like`` for homogeneous numeric sequences, which could - typically be a numpy.array. Dimensionality may be specified using ``2D``, - ``3D``, ``n-dimensional``. If you need to have variables denoting the - sizes of the dimensions, use capital letters in brackets - (``array-like (M, N)``). When refering to them in the text they are easier - read and no special formatting is needed. +Use ``array-like`` for homogeneous numeric sequences, which could +typically be a numpy.array. Dimensionality may be specified using ``2D``, +``3D``, ``n-dimensional``. If you need to have variables denoting the +sizes of the dimensions, use capital letters in brackets +(``array-like (M, N)``). When refering to them in the text they are easier +read and no special formatting is needed. - ``float`` is the implicit default dtype for array-likes. For other dtypes - use ``array-like of int``. +``float`` is the implicit default dtype for array-likes. For other dtypes +use ``array-like of int``. - Some possible uses:: +Some possible uses:: - 2D array-like - array-like (N) - array-like (M, N) - array-like (M, N, 3) - array-like of int + 2D array-like + array-like (N) + array-like (M, N) + array-like (M, N, 3) + array-like of int - Non-numeric homogeneous sequences are described as lists, e.g.:: +Non-numeric homogeneous sequences are described as lists, e.g.:: - list of str - list of `.Artist` + list of str + list of `.Artist` Referencing types - Generally, the rules from referring-to-other-code_ apply. More specifically: +~~~~~~~~~~~~~~~~~ +Generally, the rules from referring-to-other-code_ apply. More specifically: - Use full references ```~matplotlib.colors.Normalize``` with an - abbreviation tilde in parameter types. While the full name helps the - reader of plain text docstrings, the HTML does not need to show the full - name as it links to it. Hence, the ``~``-shortening keeps it more readable. +Use full references ```~matplotlib.colors.Normalize``` with an +abbreviation tilde in parameter types. While the full name helps the +reader of plain text docstrings, the HTML does not need to show the full +name as it links to it. Hence, the ``~``-shortening keeps it more readable. - Use abbreviated links ```.Normalize``` in the text. +Use abbreviated links ```.Normalize``` in the text. - .. code-block:: rst +.. code-block:: rst - norm : `~matplotlib.colors.Normalize`, optional - A `.Normalize` instance is used to scale luminance data to 0, 1. + norm : `~matplotlib.colors.Normalize`, optional + A `.Normalize` instance is used to scale luminance data to 0, 1. ``See also`` sections - Sphinx automatically links code elements in the definition blocks of ``See - also`` sections. No need to use backticks there:: +~~~~~~~~~~~~~~~~~~~~~ +Sphinx automatically links code elements in the definition blocks of ``See +also`` sections. No need to use backticks there:: - See also - -------- - vlines : vertical lines - axhline: horizontal line across the axes + See also + -------- + vlines : vertical lines + axhline: horizontal line across the axes Wrapping parameter lists - Long parameter lists should be wrapped using a ``\`` for continuation and - starting on the new line without any indent: +~~~~~~~~~~~~~~~~~~~~~~~~ +Long parameter lists should be wrapped using a ``\`` for continuation and +starting on the new line without any indent: - .. code-block:: python +.. code-block:: python - def add_axes(self, *args, **kwargs): - """ - ... + def add_axes(self, *args, **kwargs): + """ + ... - Parameters - ---------- - projection : - {'aitoff', 'hammer', 'lambert', 'mollweide', 'polar', \ - 'rectilinear'}, optional - The projection type of the axes. + Parameters + ---------- + projection : + {'aitoff', 'hammer', 'lambert', 'mollweide', 'polar', \ + 'rectilinear'}, optional + The projection type of the axes. - ... - """ + ... + """ - Alternatively, you can describe the valid parameter values in a dedicated - section of the docstring. +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"]``. Use `= [default-val]` - to indicate the default value of the parameter. The default value should be - literal, i.e. enclosed in double backticks. For simplicity these may be - omitted for string default values. +~~~~~~~~ +rcParams can be referenced with the custom ``:rc:`` role: +:literal:`:rc:\`foo\`` yields ``rcParams["foo"]``. Use `= [default-val]` +to indicate the default value of the parameter. The default value should be +literal, i.e. enclosed in double backticks. For simplicity these may be +omitted for string default values. - .. code-block:: rst +.. code-block:: rst - If not provided, defaults to :rc:`figure.figsize` = ``[6.4, 4.8]``. - If not provided, defaults to :rc:`figure.facecolor` = 'w'. + If not provided, defaults to :rc:`figure.figsize` = ``[6.4, 4.8]``. + If not provided, defaults to :rc:`figure.facecolor` = 'w'. Deprecated formatting conventions ---------------------------------