Permalink
Browse files

DOC: use bold for section names, monospace for variables in HOWTO_DOC…

…UMENT.
  • Loading branch information...
1 parent 7b75899 commit d0c0f14260e9ad758c398902288100d533ca3ea5 @endolith endolith committed with rgommers Dec 2, 2012
Showing with 14 additions and 13 deletions.
  1. +14 −13 doc/HOWTO_DOCUMENT.rst.txt
View
27 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,20 +534,20 @@ 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.
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::

0 comments on commit d0c0f14

Please sign in to comment.