Automatic Documentation and Ecto’s Sphinx Extensions

Ecto comes with a number of extensions to assist in documenting ecto-based projects. Try clicking “Show Source” on the right for a before-and-after sphinx view.... there is much less text in the source for this document than there is on this page.

.. ectocell <Module> <CellType>::

Placing the following command in sphinx:

.. ectocell:: ecto.ecto_test Add

Will import the python module ecto.ecto_test into the running Sphinx process, find the class named Add and generate documentation, which looks like this (actual output):

Add

Brief doc

Add two doubles together.

Inputs

• left   type: double   

  Left hand operand.

• right   type: double   

  Right hand operand.

Outputs

• out   type: double   

  The result.

Cells’ docstrings should contain identical information, albeit surrounded with a bit of noise:

#!/usr/bin/python

import ecto.ecto_test as ecto_test
print help(ecto_test.Add)

and the output below, which is truncated for clarity as there is quite a bit of noise, starting with Methods defined here.

.. ectoplot <file> <object>::

This directive generates and includes graph diagrams. The directive takes the name of a file and the name of an object in that file. Sphinx will execute the file, pull the named object out of the file (which must be a live plasm), get the graphviz information from the plasm, generate and include a graphic. For instance this direcive:

.. ectoplot:: ../../sampleplasm.py plasm

Will look for the file sampleplasm.py in the documentation directory, execute it, pull out and plot the object named plasm. If that script looks like this:

#!/usr/bin/python
import ecto
import ecto.ecto_test as ecto_test

plasm = ecto.Plasm()

gen = ecto_test.Generate()
inc = ecto_test.Increment()
mul = ecto_test.Multiply()
add = ecto_test.Add()

plasm.connect(gen[:] >> inc[:],
              gen[:] >> mul[:],
              mul[:] >> add['left'],
              inc[:] >> add['right'],
              )

you’ll get this:

.. program-output::

This directive has been taken from the sphinx contributions repository and souped up a bit. Extra options are:

• :until: <string>

  truncate program output after first occurrance of <string>, which may contain spaces. This is done with a simple find

• :expect_error:

  expect the script to return an error, so don’t fail if it does

• :in_srcdir:

  the path specified is relative to the filesystem location of the calling .rst file