diff options
Diffstat (limited to 'doc/HOWTO_DOCUMENT.rst.txt')
| -rw-r--r-- | doc/HOWTO_DOCUMENT.rst.txt | 25 |
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 |