From 1e6b9d32cb204d7906007c3516da26afbbd2437c Mon Sep 17 00:00:00 2001
From: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com>
Date: Tue, 28 Nov 2017 22:33:35 +0100
Subject: [PATCH] additions to the documentation guide
---
doc/devel/documenting_mpl.rst | 48 +++++++++++++++++++++++++++++++++++
1 file changed, 48 insertions(+)
diff --git a/doc/devel/documenting_mpl.rst b/doc/devel/documenting_mpl.rst
index c0222ffead54..07451f544d15 100644
--- a/doc/devel/documenting_mpl.rst
+++ b/doc/devel/documenting_mpl.rst
@@ -139,6 +139,54 @@ An example docstring looks like:
The Sphinx website also contains plenty of documentation_ concerning ReST
markup and working with Sphinx in general.
+.. note::
+
+ Some parts of the documentation do not yet conform to the current
+ documentation style. If in doubt, follow the rules given here and not what
+ you may see in the source code. Pull requests updating docstrings to
+ the current style are very welcome.
+
+Additional formatting conventions
+---------------------------------
+
+There are some additional conventions, not handled by numpydoc and the Sphinx
+guide:
+
+* We do not have a convention whether to use single-quotes or double-quotes.
+ There is a mixture of both in the current code. Please leave them as they are.
+
+* Long parameter lists should be wrapped using a ``\`` for continuation and
+ starting on the new line without any indent:
+
+ .. code-block:: python
+
+ def add_axes(self, *args, **kwargs):
+ """
+ ...
+
+ 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.
+
+* Generally, do not add markup to types for ``Parameters`` and ``Returns``.
+ This is usually not needed because Sphinx will link them automatically and
+ would unnecessarily clutter the docstring. However, it does seem to fail in
+ some situations. If you encounter such a case, you are allowed to add markup:
+
+ .. code-block:: rst
+
+ Returns
+ -------
+ lines : `~matplotlib.collections.LineCollection`
+
+
+
Linking to other code
---------------------
To link to other methods, classes, or modules in Matplotlib you can encase
pFad - Phonifier reborn
Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.
Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.
Alternative Proxies:
Alternative Proxy
pFad Proxy
pFad v3 Proxy
pFad v4 Proxy