diff options
| -rw-r--r-- | numpy/doc/HOWTO_DOCUMENT.txt | 291 |
1 files changed, 179 insertions, 112 deletions
diff --git a/numpy/doc/HOWTO_DOCUMENT.txt b/numpy/doc/HOWTO_DOCUMENT.txt index 4527af50f..c5e857916 100644 --- a/numpy/doc/HOWTO_DOCUMENT.txt +++ b/numpy/doc/HOWTO_DOCUMENT.txt @@ -1,112 +1,179 @@ - -Both NumPy and SciPy follow a convention for docstrings that provide -for some consistency while also allowing epydoc to produce -nicely-formatted reference guides. - -The docstring format uses reST syntax as interpreted by epydoc -(which should understand how to process some of our conventions at -some point) - -Here is an example: - -""" -one-line summary or signature - -Several sentences providing an extended description - -:Parameters: - var1 : type information - Explanation - var2 : type information - Explanation - long_variable_name : - Explanation - -:Returns: - named : type - Explanation - list : - Explanation - of : - Explanation - outputs : - even more explaining - -:OtherParameters: - only_seldom_used_keywords : type - Explanation - common_parametrs_listed_above : type - Explanation - -:SeeAlso: - - otherfunc : relationship (optional) - - newfunc : relationship (optional) - - -Notes ------ - -Notes about the implementation algorithm (if needed). - -This can have multiple paragraphs as can all sections. - -Examples --------- - -examples in doctest format - ->>> a=[1,2,3] ->>> [x + 3 for x in a] -[4,5,6] -""" - -Comments: - -1) The first line of the signature should **not** copy the signature. -If the function is written in C, then this first line should be the -signature. If the function signature is generic (uses *args or **kwds), -then a function signature can be included - -2) Use optional in the "type" field for parameters that are -non-keyword optional for C-functions. - -3) The OtherParameters section is for functions taking a lot of keywords -which are not always used or neeeded and whose description would clutter -then main purpose of the function. - -4) The See Also section can list additional related functions. The -purpose of this section is to direct users to other functions they may -not be aware of or have easy means to discover (i.e. by looking at the -docstring of the module). Thus, repeating functions that are in the -same module is not useful and can create a cluttered document. Please -use judgement when listing additional functions. Routines that -provide additional information in their docstrings for this function are -useful to include here. - -5) The Notes section can contain algorithmic information if that is useful. - -6) The Examples section is strongly encouraged. The examples can provide a mini-tutorial as well as additional regression testing. - - -Common reST concepts: - -A reST-documented module should define - - __docformat__ = 'restructuredtext' - -at the top level in accordance with PEP 258. Note that the -__docformat__ variable in a package's __init__.py file does not apply -to objects defined in subpackages and submodules. - -For paragraphs, indentation is significant and indicates indentation -in the output. New paragraphs are marked with blank line. - -Use *italics*, **bold**, and ``courier`` if needed in any explanations -(but not for variable names and doctest code or multi-line code) - -Use :lm:`eqn` for in-line math in latex format (remember to use the -raw-format for your text string or escape any '\' symbols). Use -:m:`eqn` for non-latex math. - -A more extensive example of reST markup can be found here: -http://docutils.sourceforge.net/docs/user/rst/demo.txt +# It is desireable that both NumPy and SciPy follow a convention for docstrings +# that provide for some consistency while also allowing epydoc to produce +# nicely-formatted reference guides. However, such a convention has not yet +# been decided on. This is my current thinking on the topic. If you have +# suggestions for improvements, post them on the numpy-dev list together with +# the epydoc output so they may be discussed. +# +# The docstring format uses reST syntax as interpreted by epydoc. The markup in +# this proposal is as basic as possible and in particular avoids the use of +# epydoc consolidated lists. This is both because there are a limited number of +# such lists, inadequate to our current needs, and because such lists are +# currently moved to the end of the documentation, messing up the ordering. So +# here standard definition lists are used. Headings likewise move around and +# have an unwelcome size in the default style sheet, hence they have also been +# avoided. +# +# A maximum line width of 79 is suggested, as this will allow the docstrings to +# display on standard terminals. This convention is a bit old and traces back +# to IBM punchcard days, but still seems to be the standard. +# +# An example follows. Line spacing and indentation are significant and should +# be carefully followed. Because this is a Python file it can be run through +# epydoc. + +__docformat__ = "restructuredtext en" + + +def foo(var1, var2, long_var_name) : + """One-line summary or signature. + + Several sentences providing an extended description. You can put + text in mono-spaced type like so: ``var``. + + *Parameters*: + + var1 : type information + Explanation + var2 : type information + Explanation + long_variable_name + Explanation + + *Returns*: + + named : type + Explanation + list + Explanation + of + Explanation + outputs + even more explaining + + *Other Parameters*: + + only_seldom_used_keywords : type + Explanation + common_parametrs_listed_above : type + Explanation + + *See Also*: + + `otherfunc` : relationship (optional) + + `newfunc` : relationship (optional) + + *Notes* + + Notes about the implementation algorithm (if needed). + + This can have multiple paragraphs as can all sections. + + *Examples* + + examples in doctest format + + >>> a=[1,2,3] + >>> [x + 3 for x in a] + [4, 5, 6] + + """ + pass + + +def newfunc() : + """Do nothing. + + I never saw a purple cow. + + """ + pass + + +def otherfunc() : + """Do nothing. + + I never hope to see one. + + """ + pass + +# Comments: +# +# 1) This is a Python file, so you can run epydoc on it like so: +# +# $ epydoc HOWTO_DOCUMENT +# +# The output will be in a directory named html in the same directory as this +# document and may be viewed by loading the index.html file into your browser. +# +# 2) The developmental version of epydoc, version 3.0 beta or later, is +# suggested as it will produce better looking output and is also faster. +# +# 3) The appearance of some of the elements can be changed in the epydoc.css +# style sheet. The list headings, i.e. *Parameters*:, are emphasized text, so +# their appearance is controlled by the definition of the <em> +# tag. For instance, to make them bold, insert +# +# em {font-weight: bold;} +# +# The variables' types are in a span of class rst-classifier, hence can be +# changed by inserting something like: +# +# span.rst-classifier {font-weight: normal;} +# +# 4) The first line of the signature should **not** copy the signature unless +# the function is written in C, in which case it is mandatory. If the function +# signature is generic (uses *args or **kwds), then a function signature may be +# included +# +# 5) Use optional in the "type" field for parameters that are non-keyword +# optional for C-functions. +# +# 6) The Other Parameters section is for functions taking a lot of keywords +# which are not always used or neeeded and whose description would clutter then +# main purpose of the function. (Comment by Chuck : I think this should be +# rarely used, if at all) +# +# 7) The See Also section can list additional related functions. The purpose +# of this section is to direct users to other functions they may not be aware +# of or have easy means to discover (i.e. by looking at the docstring of the +# module). Thus, repeating functions that are in the same module is not useful +# and can create a cluttered document. Please use judgement when listing +# additional functions. Routines that provide additional information in their +# docstrings for this function may be useful to include here. +# +# 8) The Notes section can contain algorithmic information if that is useful. +# +# 9) The Examples section is strongly encouraged. The examples can provide a +# mini-tutorial as well as additional regression testing. (Comment by Chuck: +# blank lines in the numpy output, for instance in multidimensional arrays, +# will break doctest.) You can run the tests by doing +# +# >>> import doctest +# >>> doctest.testfile('HOWTO_DOCUMENT.py') +# +# +# Common reST concepts: + +# A reST-documented module should define +# +# __docformat__ = 'restructuredtext en' +# +# at the top level in accordance with PEP 258. Note that the __docformat__ +# variable in a package's __init__.py file does not apply to objects defined in +# subpackages and submodules. +# +# For paragraphs, indentation is significant and indicates indentation in the +# output. New paragraphs are marked with blank line. +# +# Use *italics*, **bold**, and ``courier`` if needed in any explanations (but +# not for variable names and doctest code or multi-line code) +# +# Use :lm:`eqn` for in-line math in latex format (remember to use the +# raw-format for your text string or escape any '\' symbols). Use :m:`eqn` for +# non-latex math. +# +# A more extensive example of reST markup can be found here: +# http://docutils.sourceforge.net/docs/user/rst/demo.txt |