DOC: add description of how to document modules to the doc standard.

Closes #1280.

1 files changed, 25 insertions, 0 deletions

diff --git a/doc/HOWTO_DOCUMENT.rst.txt b/doc/HOWTO_DOCUMENT.rst.txt
index bbd9531e8..87f4de816 100644
--- a/doc/HOWTO_DOCUMENT.rst.txt
+++ b/doc/HOWTO_DOCUMENT.rst.txt
@@ -424,6 +424,7 @@ Method docstrings
 Document these as you would any other function.  Do not include
 ``self`` in the list of parameters.
 
+
 Documenting class instances
 ---------------------------
 Instances of classes that are part of the Numpy API (for example `np.r_`
@@ -438,6 +439,7 @@ instances a useful docstring, we do the following:
   ``__doc__`` attributes at run time. The class is documented as usual, and
   the exposed instances can be mentioned in the Notes and See Also sections.
 
+
 Documenting constants
 ---------------------
 Use the same sections as outlined for functions where applicable::
@@ -453,6 +455,29 @@ Docstrings for constants will not be visible in text terminals
 to them like for for class instances), but will appear in the
 documentation built with Sphinx.
 
+
+Documenting modules
+-------------------
+Each module should have a docstring with at least a summary line. Other
+sections are optional, and should be used in the same order as for documenting
+functions when they are appropriate::
+
+    1. summary
+    2. extended summary
+    3. routine listings
+    4. see also
+    5. notes
+    6. references
+    7. examples
+
+Routine listings are encouraged, especially for large modules, for which it is
+hard to get a good overview of all functionality provided by looking at the
+source file(s) or the __all__ dict.
+
+Note that license and author info, while often included in source files, do not
+belong in docstrings. 
+
+
 Other points to keep in mind
 ----------------------------
 * Notes and Warnings : If there are points in the docstring that deserve