matplotlib
diff --git a/‎doc/devel/documenting_mpl.rst
Copy file name to clipboardExpand all lines: doc/devel/documenting_mpl.rst
+60-73Lines changed: 60 additions & 73 deletions b/‎doc/devel/documenting_mpl.rst
Copy file name to clipboardExpand all lines: doc/devel/documenting_mpl.rst
+60-73Lines changed: 60 additions & 73 deletions
@@ -177,6 +177,47 @@ calls in `matplotlib.patches`.
 Formatting
 ==========
 
+All new or edited docstrings should conform to the numpydoc guidelines. These
+split the docstring down into a number of sections - see
+https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt for more
+details and a guide to the way docstrings should be written. A simple example
+docstring looks like:
+.. code-block:: python
+
+  def hlines(self, y, xmin, xmax, colors='k', linestyles='solid',
+               label='', **kwargs):
+        """
+        Plot horizontal lines at each `y` from `xmin` to `xmax`.
+
+        Parameters
+        ----------
+        y : scalar or sequence of scalar
+            y-indexes where to plot the lines.
+
+        xmin, xmax : scalar or 1D array_like
+            Respective beginning and end of each line. If scalars are
+            provided, all lines will have same length.
+
+        colors : array_like of colors, optional, default: 'k'
+
+        linestyles : ['solid' | 'dashed' | 'dashdot' | 'dotted'], optional
+
+        label : string, optional, default: ''
+
+        Returns
+        -------
+        lines : `~matplotlib.collections.LineCollection`
+
+        Other Parameters
+        ----------------
+        **kwargs :  `~matplotlib.collections.LineCollection` properties.
+
+        See also
+        --------
+        vlines : vertical lines
+        axhline: horizontal line across the axes
+        """
+
 The Sphinx website contains plenty of documentation_ concerning ReST markup and
 working with Sphinx in general. Here are a few additional things to keep in mind:
 
@@ -185,9 +226,11 @@ working with Sphinx in general. Here are a few additional things to keep in mind
   markup`_. For example, when referring to external files, the
   ``:file:`` directive should be used.
 
-* Function arguments and keywords should be referred to using the
-  ``*emphasis*`` role. This will keep Matplotlib's documentation consistent
-  with Python's documentation:
+Function arguments
+------------------
+Function arguments and keywords should be referred to using the
+``*emphasis*`` role. This will keep Matplotlib's documentation consistent
+with Python's documentation:
 
   .. code-block:: rst
 
@@ -206,8 +249,10 @@ working with Sphinx in general. Here are a few additional things to keep in mind
 
      Please do not describe ``argument`` like this.
 
-* Mathematical expressions can be rendered as png images in html, and in the
-  usual way by LaTeX.  For example,
+Maths
+-----
+Mathematical expressions can be rendered as png images in html, and in the
+usual way by LaTeX. For example,
 
   .. code-block:: rst
 
@@ -223,8 +268,10 @@ working with Sphinx in general. Here are a few additional things to keep in mind
 
   yields :math:`\int_{-\infty}^{\infty}\frac{e^{i\phi}}{1+x^2\frac{e^{i\phi}}{1+x^2}}`.
 
-* Interactive IPython sessions can be illustrated in the documentation using
-  the following directive:
+IPython code
+-----------
+Interactive IPython sessions can be illustrated in the documentation using
+the following directive:
 
   .. code-block:: rst
 
@@ -238,84 +285,24 @@ working with Sphinx in general. Here are a few additional things to keep in mind
 
     In [69]: lines = plot([1,2,3])
 
-* Footnotes [#]_ can be added using ``[#]_``, followed later by:
+Footnotes
+---------
+Footnotes [#]_ can be added using ``[#]_``, followed later by:
 
   .. code-block:: rst
 
     .. rubric:: Footnotes
 
     .. [#]
 
-  which yields
+which yields
 
   .. rubric:: Footnotes
 
   .. [#] For example.
 
-* Use the *note* and *warning* directives, sparingly, to draw attention to
-  important comments:
-
-  .. code-block:: rst
-
-    .. note::
-       Here is a note.
-
-    .. warning::
-       Here is a warning.
-
-  yields:
-
-  .. note::
-     Here is a note.
-
-  .. warning::
-     Here is a warning.
-
-* Use the *deprecated* directive when appropriate:
-
-  .. code-block:: rst
-
-    .. deprecated:: 0.98
-       This feature is obsolete, use something else.
-
-  yields:
-
-  .. deprecated:: 0.98
-     This feature is obsolete, use something else.
-
-* Use the *versionadded* and *versionchanged* directives, which have similar
-  syntax to the *deprecated* role:
-
-  .. code-block:: rst
-
-    .. versionadded:: 0.98
-       The transforms have been completely revamped.
-
-  .. versionadded:: 0.98
-     The transforms have been completely revamped.
-
-* Use the *seealso* directive, for example:
-
-  .. code-block:: rst
-
-    .. seealso::
-
-       Using ReST :ref:`emacs-helpers`:
-          One example
-
-       A bit about :ref:`referring-to-mpl-docs`:
-          One more
-
-  yields:
-
-  .. seealso::
-
-     Using ResT :ref:`emacs-helpers`:
-        One example
-
-     A bit about :ref:`referring-to-mpl-docs`:
-        One more
-
+Other
+-----
 * Please keep the :ref:`glossary` in mind when writing documentation. You can
   create a references to a term in the glossary with the ``:term:`` role.