@@ -139,6 +139,54 @@ An example docstring looks like:
139139documentation _ concerning ReST
140140markup and working with Sphinx in general.
141141
142+ .. note ::
143+
144+ Some parts of the documentation do not yet conform to the current
145+ documentation style. If in doubt, follow the rules given here and not what
146+ you may see in the source code. Pull requests updating docstrings to
147+ the current style are very welcome.
148+
149+ Additional formatting conventions
150+ ---------------------------------
151+
152+ There are some additional conventions, not handled by numpydoc and the Sphinx
153+ guide:
154+
155+ * We do not have a convention whether to use single-quotes or double-quotes.
156+ There is a mixture of both in the current code. Please leave them as they are.
157+
158+ * Long parameter lists should be wrapped using a ``\ `` for continuation and
159+ starting on the new line without any indent:
160+
161+ .. code-block :: python
162+
163+ def add_axes (self * args , ** kwargs ):
164+ """
165+ ...
166+
167+ Parameters
168+ ----------
169+ projection :
170+ ['aitoff' | 'hammer' | 'lambert' | 'mollweide' | \
171+ 'polar' | 'rectilinear'], optional
172+ The projection type of the axes.
173+
174+ Alternatively, you can describe the valid parameter values in a dedicated
175+ section of the docstring.
176+
177+ * Generally, do not add markup to types for ``Parameters`` and ``Returns``.
178+ This is usually not needed because Sphinx will link them automatically and
179+ would unnecessarily clutter the docstring. However, it does seem to fail in
180+ some situations. If you encounter such a case, you are allowed to add markup:
181+
182+ .. code-block:: rst
183+
184+ Returns
185+ -------
186+ lines : `~matplotlib.collections.LineCollection`
187+
188+
189+
142190Linking to other code
143191---------------------
144192To link to other methods, classes, or modules in Matplotlib you can encase
0 commit comments