[Numpy-svn] r4016 - trunk/numpy/doc

numpy-svn@scip... numpy-svn@scip...
Mon Aug 27 23:37:54 CDT 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