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:

digraph G {
graph [rankdir=TB, ranksep=1]
edge [labelfontsize=8]
node [shape=plaintext]
0[label=<<TABLE BORDER="0" CELLBORDER="1" CELLSPACING="0" CELLPADDING="4">  <TR> <TD ROWSPAN="3" COLSPAN="1" BGCOLOR="khaki">ecto_test::Generate&lt;double&gt;</TD> <TD PORT="p_start" BGCOLOR="lightblue">start</TD>
 </TR> <TR> <TD PORT="p_step" BGCOLOR="lightblue">step</TD> </TR>
<TR> <TD PORT="p_stop" BGCOLOR="lightblue">stop</TD> </TR>
 <TR>
<TD PORT="o_out" BGCOLOR="indianred1">out</TD>
</TR> </TABLE>>];
1[label=<<TABLE BORDER="0" CELLBORDER="1" CELLSPACING="0" CELLPADDING="4"> <TR>
<TD PORT="i_in" BGCOLOR="springgreen">in</TD>
</TR> <TR> <TD ROWSPAN="2" COLSPAN="1" BGCOLOR="khaki">ecto_test::Increment</TD> <TD PORT="p_amount" BGCOLOR="lightblue">amount</TD>
 </TR> <TR> <TD PORT="p_delay" BGCOLOR="lightblue">delay</TD> </TR>
 <TR>
<TD PORT="o_out" BGCOLOR="indianred1">out</TD>
</TR> </TABLE>>];
2[label=<<TABLE BORDER="0" CELLBORDER="1" CELLSPACING="0" CELLPADDING="4"> <TR>
<TD PORT="i_in" BGCOLOR="springgreen">in</TD>
</TR> <TR> <TD ROWSPAN="1" COLSPAN="1" BGCOLOR="khaki">ecto_test::Multiply</TD> <TD PORT="p_factor" BGCOLOR="lightblue">factor</TD>
 </TR>  <TR>
<TD PORT="o_out" BGCOLOR="indianred1">out</TD>
</TR> </TABLE>>];
3[label=<<TABLE BORDER="0" CELLBORDER="1" CELLSPACING="0" CELLPADDING="4"> <TR>
<TD PORT="i_left" BGCOLOR="springgreen">left</TD>
<TD PORT="i_right" BGCOLOR="springgreen">right</TD>
</TR> <TR> <TD ROWSPAN="1" COLSPAN="2" BGCOLOR="khaki">ecto_test::Add</TD>  </TR>  <TR>
<TD PORT="o_out" BGCOLOR="indianred1">out</TD>
</TR> </TABLE>>];
0->1 [headport="i_in" tailport="o_out"];
0->2 [headport="i_in" tailport="o_out"];
2->3 [headport="i_left" tailport="o_out"];
1->3 [headport="i_right" tailport="o_out"];
}

.. 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