[Numpy-svn] r4016 - trunk/numpy/doc
numpy-svn at scipy.org
numpy-svn at scipy.org
Tue Aug 28 00:37:54 EDT 2007
Author: charris
Date: 2007-08-27 23:37:50 -0500 (Mon, 27 Aug 2007)
New Revision: 4016
Modified:
trunk/numpy/doc/HOWTO_DOCUMENT.txt
Log:
Revise HOWTO_DOCUMENT.txt to make it work.
Modified: trunk/numpy/doc/HOWTO_DOCUMENT.txt
===================================================================
--- trunk/numpy/doc/HOWTO_DOCUMENT.txt 2007-08-27 01:43:26 UTC (rev 4015)
+++ trunk/numpy/doc/HOWTO_DOCUMENT.txt 2007-08-28 04:37:50 UTC (rev 4016)
@@ -1,112 +1,179 @@
+# 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.
-Both NumPy and SciPy follow a convention for docstrings that provide
-for some consistency while also allowing epydoc to produce
-nicely-formatted reference guides.
+__docformat__ = "restructuredtext en"
-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:
+def foo(var1, var2, long_var_name) :
+ """One-line summary or signature.
-"""
-one-line summary or signature
+ Several sentences providing an extended description. You can put
+ text in mono-spaced type like so: ``var``.
-Several sentences providing an extended description
+ *Parameters*:
-:Parameters:
- var1 : type information
- Explanation
- var2 : type information
- Explanation
- long_variable_name :
- Explanation
+ var1 : type information
+ Explanation
+ var2 : type information
+ Explanation
+ long_variable_name
+ Explanation
-:Returns:
- named : type
- Explanation
- list :
- Explanation
- of :
- Explanation
- outputs :
- even more explaining
+ *Returns*:
-:OtherParameters:
- only_seldom_used_keywords : type
- Explanation
- common_parametrs_listed_above : type
- Explanation
+ named : type
+ Explanation
+ list
+ Explanation
+ of
+ Explanation
+ outputs
+ even more explaining
-:SeeAlso:
- - otherfunc : relationship (optional)
- - newfunc : relationship (optional)
+ *Other Parameters*:
+ only_seldom_used_keywords : type
+ Explanation
+ common_parametrs_listed_above : type
+ Explanation
-Notes
------
+ *See Also*:
-Notes about the implementation algorithm (if needed).
+ `otherfunc` : relationship (optional)
-This can have multiple paragraphs as can all sections.
+ `newfunc` : relationship (optional)
-Examples
---------
+ *Notes*
-examples in doctest format
+ Notes about the implementation algorithm (if needed).
->>> a=[1,2,3]
->>> [x + 3 for x in a]
-[4,5,6]
-"""
+ This can have multiple paragraphs as can all sections.
-Comments:
+ *Examples*
-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
+ examples in doctest format
-2) Use optional in the "type" field for parameters that are
-non-keyword optional for C-functions.
+ >>> a=[1,2,3]
+ >>> [x + 3 for x in a]
+ [4, 5, 6]
-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.
+ """
+ pass
-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.
+def newfunc() :
+ """Do nothing.
-6) The Examples section is strongly encouraged. The examples can provide a mini-tutorial as well as additional regression testing.
+ I never saw a purple cow.
+ """
+ pass
-Common reST concepts:
-A reST-documented module should define
+def otherfunc() :
+ """Do nothing.
- __docformat__ = 'restructuredtext'
+ I never hope to see one.
-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.
+ """
+ pass
-For paragraphs, indentation is significant and indicates indentation
-in the output. New paragraphs are marked with blank line.
+# 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:
-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
+# 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
More information about the Numpy-svn
mailing list