DOC : minor tweaks to coding_guide

- strengthen suggestion to use auto pep8 checker - added example minimal numpydoc docstring
matplotlib · tacaswell · Jun 29, 2014 · Jun 29, 2014 · Jun 30, 2014 · Jun 30, 2014
commit 050f3af6e4231db51e3d8a26b60c2c5ffdaf6e9f
diff --git a/doc/devel/coding_guide.rst b/doc/devel/coding_guide.rst
@@ -34,8 +34,9 @@ Style
   <http://www.python.org/dev/peps/pep-0008/>`_.  Exceptions to these
   rules are acceptable if it makes the code objectively more readable.
 
-  - You may want to consider installing automatic PEP8 checking in
-    your editor.
+  - You should installing/enabling automatic PEP8 checking in your
+    editor.  Part of the test suite in checking PEP8 compliance, things
+    go smoother if the code is mostly PEP8 compliant to begin with.
 
 * No tabs (only spaces).  No trailing whitespace.
 
@@ -63,18 +64,43 @@ Documentation
 -------------
 
 * Every new feature should be documented.  If it's a new module, don't
-  forget to add it to the API docs.
+  forget to add a new rst file to the API docs.
 
 * Docstrings should be in `numpydoc format
   <https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt>`_.
   Don't be thrown off by the fact that many of the existing docstrings
   are not in that format.  We are working to standardize on
   `numpydoc`.
 
+  Docstrings should look like (at a minimum)::
+
+      def foo(bar, baz=None):
+          """
+          This is a prose description of foo and all the great
+          things it does.
+
+	  Parameters
+	  ----------
+	  bar : (type of bar)
+	      A description of bar
+
+	  baz : (type of baz), optional
+	      A description of baz
+
+	  Returns
+	  -------
+	  foobar : (type of foobar)
+	      A description of foobar
+	  foobaz : (type of foobaz)
+	      A description of foobaz
+          """
+	  # some very clever code
+	  return foobar, foobaz
+
 * Each high-level plotting function should have a simple example in
-  the `Example` section.  This should be as simple as possible to
-  demonstrate the method.  More complex examples should go in the
-  `examples` tree.
+  the `Example` section of the docstring.  This should be as simple as
+  possible to demonstrate the method.  More complex examples should go
+  in the `examples` tree.
 
 * Build the docs and make sure all formatting warnings are addressed.