beginning to switch to epydoc+rst documentation

doc/build_html.sh

+#!/bin/bash
+
+APIRST2HTML=~/bin/apirst2html.py
+
+EPYDOC_ARGS='--external-api=api --external-api-file=api:../html/api/api-objects.txt --external-api-root=api:epydoc/'
+
+mkdir html 2> /dev/null
+
+for RST in graph ;  do
+    $APIRST2HTML $EPYDOC_ARGS $RST.txt html/$RST.html
+done

doc/doc.idx

+graph	/graph.html
+tensor	/graph.html
+result	/graph.html
+howto	/graph.html

doc/graph.txt

+What is a Graph
+===============
+
+Some text, pictures, etc.
+
+
+:api:`tensor.Tensor`
+
+
+Subtitle
+--------
+
+Here is some stuff.
+
+ .. code-block::
+  def fib(n):
+     if n == 0:
+       return 1
+     if n == 1:
+       return 1
+     return fib(n-1) + fib(n-1)
+
+ .. python::
+  def fib(n):
+     if n == 0:
+       return 1
+     if n == 1:
+       return 1
+     return fib(n-1) + fib(n-1)

gof/op.py

 """
-Contains the L{Op} class, which is the base interface for all operations
-compatible with gof's graph manipulation routines.
+Contains the `Op` class, which is the base interface for all operations
+compatible with `gof`'s :doc:`graph` manipulation routines.
 """
 
+__docformat__ = "restructuredtext en"
+
 import utils
 import traceback
 
 
 class Op(utils.object2):
+    """
+    An :term:`Op` is a type of operation.
+
+    `Op` is an abstract class that documents the interface for theano's data transformations.
+    It has many subclasses, such as 
+    `sparse dot <http://lgcm.iro.umontreal.ca/epydoc/theano.sparse.Dot-class.html>`__,
+    and `Shape <http://lgcm.iro.umontreal.ca/epydoc/theano.tensor.Shape-class.html>`__.
+
+    These subclasses are meant to be instantiated.  
+    An instance has several responsabilities:
+
+    - making `Apply` instances, which mean "apply this type of operation to some particular inputs" (via `make_node`),
+
+    - performing the calculation of outputs from given inputs (via the `perform`),
+
+    - producing c code to perform calculation of outputs from inputs (via `c_code`, 
+      `c_code_cleanup`, `c_support_code`, `c_headers`, `c_libraries`, `c_compile_args`)
+
+    - [optionally] building gradient-calculating graphs (via `grad`).
+
+
+    To see how `Op`, `Type`, `Result`, and `Apply` fit together see the page on :doc:`graph`.
+
+    """
 
     default_output = None
-    """@todo
-    WRITEME
+    """ 
+    configuration variable for `__call__`
+
+    A subclass should not change this class variable, but instead over-ride it with a subclass
+    variable or an instance variable.
+
     """
     
     #############
@@ -20,17 +50,34 @@ class Op(utils.object2):
 
     def make_node(self, *inputs):
         """
-        This function should return an Apply instance representing the
-        application of this Op on the provided inputs.
+        Contract: return an Apply instance representing the
+        application of this Op to the provided inputs.
+
+        All subclasses should over-ride this function.
+
+        :Exceptions:
+         - `AbstractFunctionError`: the subclass does not override this method
+
         """
         raise utils.AbstractFunctionError(self)
 
     def __call__(self, *inputs):
         """
-        Shortcut for:
-          self.make_node(*inputs).outputs[self.default_output] (if default_output is defined)
-          self.make_node(*inputs).outputs[0] (if only one output)
-          self.make_node(*inputs).outputs (if more than one output)
+        Return some or all output[s] of `make_node`.  
+
+        It is called by code such as:
+
+        .. python::
+
+           x = tensor.matrix()
+
+           # tensor.exp is an Op instance, calls Op.__call__(self=<instance of exp>, inputs=(x,))
+           y = tensor.exp(x)      
+           
+        This class implements a convenience function (for graph-building) which uses
+        `default_output`, but subclasses are free to override this function and ignore
+        `default_output`.
+
         """
         node = self.make_node(*inputs)
         node.tag.trace = traceback.extract_stack()[:-1]
@@ -49,18 +96,25 @@ class Op(utils.object2):
 
     def perform(self, node, inputs, output_storage):
         """
-        Calculate the function on the inputs and put the results in the
-        output storage.
+        Contract:  Calculate the function on the inputs and put the results in the
+        output storage.  Return None.
 
-        - node: Apply instance that contains the symbolic inputs and outputs
-        - inputs: sequence of inputs (immutable)
-        - output_storage: list of mutable 1-element lists (do not change
-                          the length of these lists)
+        :Parameters:
+         `node`: Apply instance 
+            contains the symbolic inputs and outputs
+         `inputs`: list
+            sequence of inputs (immutable)
+         `output_storage`: list
+             list of mutable 1-element lists (do not change the length of these lists)
 
-        The output_storage list might contain data. If an element of
+        The `output_storage` list might contain data. If an element of
         output_storage is not None, it is guaranteed that it was produced
         by a previous call to impl and impl is free to reuse it as it
         sees fit.
+
+        :Exceptions:
+         - `AbstractFunctionError`: the subclass does not override this method
+
         """
         raise utils.AbstractFunctionError(self)
 
@@ -69,23 +123,26 @@ class Op(utils.object2):
     #####################
 
     def c_code(self, node, name, inputs, outputs, sub):
-        """Return the C implementation of an Op.
+        """Contract: Return the C implementation of an Op.
 
         Returns C code that does the computation associated to this L{Op},
         given names for the inputs and outputs.
         
-        @param inputs: list of strings.  There is a string for each input
-                       of the function, and the string is the name of a C
-                       L{PyObject}* variable pointing to that input.
-
-        @param outputs: list of strings.  Each string is the name of a
-                        L{PyObject}* pointer where the Op should store its
-                        results.  The L{CLinker} guarantees that on entry to
-                        this code block, each pointer is either NULL or is
-                        unchanged from the end of the previous execution.
-
-        @param sub: extra symbols defined in L{CLinker sub symbols} (such as
-                'fail').
+        :Parameters:
+         `node`: Apply instance
+           WRITEME
+         `name`: WRITEME
+           WRITEME
+         `inputs`: list of strings
+           There is a string for each input of the function, and the string is the name of a C
+           `PyObject` variable pointing to that input.
+         `outputs`: list of strings
+           Each string is the name of a `PyObject` pointer where the Op should store its
+           results.  The `CLinker` guarantees that on entry to this code block, each pointer
+           is either NULL or is unchanged from the end of the previous execution.
+         `sub`: dict of strings
+           extra symbols defined in `CLinker` sub symbols (such as 'fail').
+           WRITEME
 
         """
         raise utils.AbstractFunctionError('%s.c_code is not defined' \
@@ -96,12 +153,15 @@ class Op(utils.object2):
 
         This is a convenient place to clean up things allocated by c_code().  
         
+        WRITEME
         """
         raise utils.AbstractFunctionError()
 
     def c_compile_args(self):
         """
         Return a list of compile args recommended to manipulate this L{Op}.
+
+        WRITEME
         """
         raise utils.AbstractFunctionError()
 
@@ -109,12 +169,16 @@ class Op(utils.object2):
         """
         Return a list of header files that must be included from C to manipulate
         this L{Op}.
+
+        WRITEME
         """
         raise utils.AbstractFunctionError()
 
     def c_libraries(self):
         """
         Return a list of libraries to link against to manipulate this L{Op}.
+
+        WRITEME
         """
         raise utils.AbstractFunctionError()
 
@@ -122,6 +186,8 @@ class Op(utils.object2):
         """
         Return utility code for use by this L{Op}. It may refer to support code
         defined for its input L{Result}s.
+
+        WRITEME
         """
         raise utils.AbstractFunctionError()
 

local.build_html.sh

+#!/bin/bash
+
+epydoc --config local.epydoc
+
+cd doc
+sh build_html.sh
+cd ../
+rm -Rf html/doc
+mv doc/html html/doc
+

local.epydoc

+# TODO:
+#   Get all graphs to work!
+
+
+[epydoc] # Epydoc section marker (required by ConfigParser)
+
+# The list of objects to document.  Objects can be named using
+# dotted names, module filenames, or package directory names.
+# Alases for this option include "objects" and "values".
+modules: *.py, gof/*.py
+
+# The type of output that should be generated.  Should be one
+# of: html, text, latex, dvi, ps, pdf.
+output: html
+
+# The path to the output directory.  May be relative or absolute.
+target: html/api/
+
+# An integer indicating how verbose epydoc should be.  The default
+# value is 0; negative values will supress warnings and errors;
+# positive values will give more verbose output.
+verbosity: 1
+
+# A boolean value indicating that Epydoc should show a tracaback
+# in case of unexpected error. By default don't show tracebacks
+debug: 0
+
+# If True, don't try to use colors or cursor control when doing
+# textual output. The default False assumes a rich text prompt
+simple-term: 0
+
+
+### Generation options
+
+# The default markup language for docstrings, for modules that do
+# not define __docformat__.  Defaults to epytext.
+docformat: epytext
+
+# Whether or not parsing should be used to examine objects.
+parse: yes
+
+# Whether or not introspection should be used to examine objects.
+introspect: yes
+
+# Don't examine in any way the modules whose dotted name match this
+# regular expression pattern.
+#exclude
+
+# Don't perform introspection on the modules whose dotted name match this
+# regular expression pattern.
+#exclude-introspect
+
+# Don't perform parsing on the modules whose dotted name match this
+# regular expression pattern.
+#exclude-parse
+
+# The format for showing inheritance objects.
+# It should be one of: 'grouped', 'listed', 'included'.
+inheritance: grouped
+
+# Whether or not to inclue private variables.  (Even if included,
+# private variables will be hidden by default.)
+private: yes
+
+# Whether or not to list each module's imports.
+imports: yes
+
+# Whether or not to include syntax highlighted source code in
+# the output (HTML only).
+sourcecode: yes
+
+# Whether or not to includea a page with Epydoc log, containing
+# effective option at the time of generation and the reported logs.
+include-log: yes
+
+
+### Output options
+
+# The documented project's name.
+name: Theano
+
+# The CSS stylesheet for HTML output.  Can be the name of a builtin
+# stylesheet, or the name of a file.
+css: white
+
+# The documented project's URL.
+url: http://lgcm.iro.umontreal.ca/theano/
+
+# HTML code for the project link in the navigation bar.  If left
+# unspecified, the project link will be generated based on the
+# project's name and URL.
+#link: <a href="somewhere">My Cool Project</a>
+
+# The "top" page for the documentation.  Can be a URL, the name
+# of a module or class, or one of the special names "trees.html",
+# "indices.html", or "help.html"
+#top: os.path
+
+# An alternative help file.  The named file should contain the
+# body of an HTML file; navigation bars will be added to it.
+#help: my_helpfile.html
+
+# Whether or not to include a frames-based table of contents.
+#frames: yes
+frames: no
+
+# Whether each class should be listed in its own section when
+# generating LaTeX or PDF output.
+separate-classes: no
+
+
+### API linking options
+
+# Define a new API document.  A new interpreted text role
+# will be created
+#external-api: epydoc
+
+# Use the records in this file to resolve objects in the API named NAME.
+#external-api-file: epydoc:api-objects.txt
+
+# Use this URL prefix to configure the string returned for external API.
+#external-api-root: epydoc:http://epydoc.sourceforge.net/api
+external-api: wiki
+external-api-root: wiki:http://lgcm.iro.umontreal.ca/theano/wiki/
+external-api-file: wiki:theano/wiki.idx
+
+external-api: doc
+external-api-root: doc:http://lgcm.iro.umontreal.ca/doc/
+external-api-file: doc:doc/doc.idx
+
+### Graph options
+
+# The list of graph types that should be automatically included
+# in the output.  Graphs are generated using the Graphviz "dot"
+# executable.  Graph types include: "classtree", "callgraph",
+# "umlclass".  Use "all" to include all graph types
+graph: classtree
+
+# The path to the Graphviz "dot" executable, used to generate
+# graphs.
+dotpath: /usr/bin/dot
+
+# The name of one or more pstat files (generated by the profile
+# or hotshot module).  These are used to generate call graphs.
+#pstat: autotest.pstat
+
+# Specify the font used to generate Graphviz graphs.
+# (e.g., helvetica or times).
+graph-font: Helvetica
+
+# Specify the font size used to generate Graphviz graphs.
+graph-font-size: 10
+
+
+### Return value options
+
+# The condition upon which Epydoc should exit with a non-zero
+# exit status. Possible values are error, warning, docstring_warning
+#fail-on: error