diff options
author | endolith <endolith@gmail.com> | 2012-12-02 12:42:51 -0500 |
---|---|---|
committer | Ralf Gommers <ralf.gommers@googlemail.com> | 2012-12-04 21:25:07 +0100 |
commit | d0c0f14260e9ad758c398902288100d533ca3ea5 (patch) | |
tree | 1cfda2d99a68daa356f2cc1e4c1df2b476378ad8 /doc | |
parent | 7b75899f586ee476affbf89572d0105996725d94 (diff) | |
download | numpy-d0c0f14260e9ad758c398902288100d533ca3ea5.tar.gz |
DOC: use bold for section names, monospace for variables in HOWTO_DOCUMENT.
Diffstat (limited to 'doc')
-rw-r--r-- | doc/HOWTO_DOCUMENT.rst.txt | 27 |
1 files changed, 14 insertions, 13 deletions
diff --git a/doc/HOWTO_DOCUMENT.rst.txt b/doc/HOWTO_DOCUMENT.rst.txt index 876d53277..278797c9a 100644 --- a/doc/HOWTO_DOCUMENT.rst.txt +++ b/doc/HOWTO_DOCUMENT.rst.txt @@ -422,7 +422,7 @@ applicable). The constructor (``__init__``) should also be documented here, the **parameters** section of the docstring details the constructors parameters. -An ``Attributes`` section, located below the **parameters** section, +An **Attributes** section, located below the **parameters** section, may be used to describe class variables:: Attributes @@ -448,7 +448,7 @@ In general, it is not necessary to list class methods. Those that are not part of the public API have names that start with an underscore. In some cases, however, a class may have a great many methods, of which only a few are relevant (e.g., subclasses of ndarray). Then, it -becomes useful to have an additional ``Methods`` section:: +becomes useful to have an additional **methods** section:: class Photo(ndarray): """ @@ -472,7 +472,7 @@ becomes useful to have an additional ``Methods`` section:: If it is necessary to explain a private method (use with care!), it can be referred to in the **extended summary** or the **notes**. Do not -list private methods in the Methods section. +list private methods in the **methods** section. Note that `self` is *not* listed as the first parameter of methods. @@ -482,8 +482,8 @@ Document these as you would any other function. Do not include ``self`` in the list of parameters. If a method has an equivalent function (which is the case for many ndarray methods for example), the function docstring should contain the detailed documentation, and the method docstring -should refer to it. Only put brief summary and See Also sections in the method -docstring. +should refer to it. Only put brief summary and **See Also** sections in the +method docstring. Documenting class instances @@ -498,7 +498,8 @@ instances a useful docstring, we do the following: * Multiple instances: If multiple instances are exposed, docstrings for each instance are written and assigned to the instances' ``__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. + the exposed instances can be mentioned in the **Notes** and **See Also** + sections. Documenting constants @@ -533,7 +534,7 @@ functions when they are appropriate:: 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. +source file(s) or the ``__all__`` dict. Note that license and author info, while often included in source files, do not belong in docstrings. @@ -541,12 +542,12 @@ belong in docstrings. Other points to keep in mind ---------------------------- -* Equations : as discussed in the Notes section above, LaTeX formatting should - be kept to a minimum. Often it's possible to show equations as Python code - or pseudo-code instead, which is much better readable in a terminal. For - inline display use double backticks (like ``y = np.sin(x)``). For display - with blank lines above and below, use a double colon and indent the code, - like:: +* Equations : as discussed in the **Notes** section above, LaTeX formatting + should be kept to a minimum. Often it's possible to show equations as + Python code or pseudo-code instead, which is much better readable in a + terminal. For inline display use double backticks (like ``y = np.sin(x)``). + For display with blank lines above and below, use a double colon and indent + the code, like:: end of previous sentence:: |