Documentation Tools (paver.doctools)

Tasks and utility functions and classes for working with project documentation.

class paver.doctools.Includer(basedir, cog=None, include_markers=None)

Looks up SectionedFiles relative to the basedir.

When called with a filename and an optional section, the Includer will:

1. look up that file relative to the basedir in a cache
2. load it as a SectionedFile if it’s not in the cache
3. return the whole file if section is None
4. return just the section desired if a section is requested

If a cog object is provided at initialization, the text will be sent to the CogGenerator (cog.gen) rather than returned as a string.

You can pass in include_markers which is a dictionary that maps file extensions to the single line comment character for that file type. If there is an include marker available, then output like:

# section ‘sectionname’ from ‘file.py’

There are some default include markers. If you don’t pass in anything, no include markers will be displayed. If you pass in an empty dictionary, the default ones will be displayed.

class paver.doctools.SectionedFile(filename=None, from_string=None)

Loads a file into memory and keeps track of all of the sections found in the file. Sections are started with a line that looks like this:

[[[section SECTIONNAME]]]

Anything else can appear on the line outside of the brackets (so if you’re in a source code file, you can put the section marker in a comment). The entire lines containing the section markers are not included when you request the text from the file.

An end of section marker looks like this:

[[[endsection]]]

Sections can be nested. If you do nest sections, you will use dotted notation to refer to the inner sections. For example, a “dessert” section within an “order” section would be referred to as “order.dessert”.

The SectionedFile provides dictionary-style access to the sections. If you have a SectionedFile named ‘sf’, sf[sectionname] will give you back a string of that section of the file, including any inner sections. There won’t be any section markers in that string.

You can get the text of the whole file via the all property (for example, sf.all).

Section names must be unique across the file, but inner section names are kept track of by the full dotted name. So you can have a “dessert” section that is contained within two different outer sections.

Ending a section without starting one or ending the file without ending a section will yield BuildFailures.

all

Property to get access to the whole file.

paver.doctools.cog(options)

Runs the cog code generator against the files matching your specification. By default, cog will run against any .rst files in your Sphinx document root. Full documentation for Cog is here:

http://nedbatchelder.com/code/cog/

In a nutshell, you put blocks in your file that look like this:

[[[cog cog.outl(“Hi there!”) ]]] [[[end]]]

Cog will replace the space between ]]] and [[[end]]] with the generated output. In this case, Hi there!

Here are the options available for the cog task. These are looked up in the ‘cog’ options section by default. The ‘sphinx’ option set is also searched.

basedir

directory to look in for files to cog. If not set, ‘docroot’ is looked up.

pattern

file glob to look for under basedir. By default, *.rst

includedir

If you have external files to include in your documentation, setting includedir to the root of those files will put a paver.doctools.Includer in your Cog namespace as ‘include’. This lets you easily include files and sections of files. Here’s an example usage:

[[[cog include('filename_under_includedir.py', 'mysection')]]]
[[[end]]]

defines

Dictionary of objects added to your Cog namespace. (can supersede ‘include’ and ‘sh’ defined by includedir.)

beginspec

String used at the beginning of the code generation block. Default: [[[cog

endspec

String used at the end of the code generation block. Default; ]]]

endoutput

String used at the end of the generated output Default: [[[end]]]

delete_code

Remove the generator code. Note that this will mean that the files that get changed cannot be changed again since the code will be gone. Default: False

include_markers

Dictionary mapping file extensions to the single line comment marker for that file. There are some defaults. For example, ‘py’ maps to ‘# ‘. If there is a known include marker for a given file, then a comment will be displayed along the lines of:

# section ‘SECTIONNAME’ in file ‘foo.py’

If this option is not set, these lines will not be displayed at all. If this option is set to an empty dictionary, the default include markers will be displayed. You can also pass in your own extension -> include marker settings.

paver.doctools.doc_clean()

Clean (delete) the built docs. Specifically, this deletes the build directory under the docroot. See the html task for the options list.

paver.doctools.html()

Build HTML documentation using Sphinx. This uses the following options in a “sphinx” section of the options.

docroot

the root under which Sphinx will be working. Default: docs

builddir

directory under the docroot where the resulting files are put. default: build

sourcedir

directory under the docroot for the source files default: (empty string)

paver.doctools.uncog(options)

Remove the Cog generated code from files. Often, you will want to do this before committing code under source control, because you don’t generally want generated code in your version control system.

This takes the same options as the cog task. Look there for more information.