Merge pull request #10280 from timhoffm/documentation-guide

tacaswell · web-flow · commit bd75712cd7f1 · 2018-01-21T19:04:05.000-05:00
DOC: Update writing docs concerning explicit parameter lists
diff --git a/doc/devel/documenting_mpl.rst b/doc/devel/documenting_mpl.rst
@@ -337,7 +337,7 @@ An example docstring looks like:
 
         colors : array_like of colors, optional, default: 'k'
 
-        linestyles : ['solid' | 'dashed' | 'dashdot' | 'dotted'], optional
+        linestyles : {'solid', 'dashed', 'dashdot', 'dotted'}, optional
 
         label : string, optional, default: ''
 
@@ -389,10 +389,9 @@ to keep in mind:
          Parameters
          ----------
          projection :
-             ['aitoff' | 'hammer' | 'lambert' | 'mollweide' | \
-     'polar' | 'rectilinear'], optional
+             {'aitoff', 'hammer', 'lambert', 'mollweide', 'polar', \
+     'rectilinear'}, optional
              The projection type of the axes.
-        """
 
          ...
          """
@@ -411,6 +410,14 @@ to keep in mind:
      -------
      lines : `~matplotlib.collections.LineCollection`
 
+
+Deprecated formatting conventions
+---------------------------------
+* Formerly, we have used square brackets for explicit parameter lists
+  ``['solid' | 'dashed' | 'dotted']``. With numpydoc we have switched to their
+  standard using curly braces ``{'solid', 'dashed', 'dotted'}``.
+
+
 Linking to other code
 ---------------------
 To link to other methods, classes, or modules in Matplotlib you can encase
