The documentation module

Scripts for building or compiling the software API

This module provides scripts for reading through the source code, pulling out the docstrings, and generating HTML API from them. The output will be copied to the doc/api directory.

Functions

src.dev.documentation.toHeader(string, level)

Construct a reST header from a string.

Parameters :

string : str

The string which should constitute the header.

level : int

The section level (i.e. if 0 is “part”, then 1 is “chapter”, 2 is “section”, and so on).

Returns :

str :

A string containing the input string with the appropriate markers below and possibly above it (as determined by level).

src.dev.documentation.toImportPath(path)

Convert a path to an import path.

Parameters :

path : str

A proper, absolute file path.

Returns :

str :

An import path (period-separated) relative to the home folder.

src.dev.documentation.toOutputModuleFile(path)

Construct the output file path for a module.

The form of the output path is api_[packages]_[module name].rst, where [packages] is an underscore-separated sequence of package names leading to the module, but not including “src”.

Parameters :

path : str

A proper, absolute file path for a module.

Returns :

str :

The output path (with extension ”.rst”) for the module documentation file.

src.dev.documentation.toOutputPackageFile(path)

Construct the output file path for a package.

If path refers to the top level of the source tree, the output is “index.rst”. Otherwise, it is an underscore-separated list of path elements relative to the project home, beginning with “api” and not including “src”.

Parameters :

path : str

A proper, absolute file path for a module.

Returns :

str :

The output path (with extension ”.rst”) for the package documentation file.

src.dev.documentation.processModule(path)

Create a documentation file for a module.

The output file consists of the following parts:

1. The properly formatted module docstring.
2. The classes contained in the module. Each class gets its own sub-section, and all public methods are listed.
3. The functions contained in the module.

Parameters :

path : str

The absolute path to the module.

src.dev.documentation.processPackage(path, children, childPackages)

Construct the documentation file for a package.

The file consists first of the docstring from the package’s __init__ module. Then follows a list of the contents of the package. Its modules come first, and the sub-packages follow.

Parameters :

children : list of str

A list of the paths of the modules in the package.

childPackages : list of str

A list of the paths of the sub-packages in the package.

src.dev.documentation.formatHTMLHelp()

Format HTML Help files so that wxPython can display them.

src.dev.documentation.generateManualHTMLHelp()

Produce the manual in the Microsoft HTML Help format.

Remove the old documentation from doc/htmlhelp. Then generate the new files by running the make file. Process these files to make them suitable for inclusion in wxPython’s HTML Help frames, and run them through my own script to get the syntax highlighting done properly. Finally, move the result into the doc folder and delete the build directory.

src.dev.documentation.generateManualPDF()

Generate a PDF of the documentation.

Delete the old PDF. Then set the PYTHONPATH to include the Transport directory. Run the make file to prepare the LaTeX sources. Then run pdflatex (twice to make sure contents and indices get updated). Move the resulting PDF into the project home folder. Delete the documentation build directory to avoid keeping old files.

src.dev.documentation.generateAPI()

Extract the docstrings from the desired modules and create HTML API.

First, remove the previous version of the documentation from the src/api directory. Then run the make.bat file generated by the sphinx-quickstart script to convert this to HTML. Finally, move the output back into the src/api directory.

src.dev.documentation.copySvnAdminAreas(sourcetop, destinationtop)

Copy the SVN admin areas without connecting to the repository.

src.dev.documentation.updateVersion(filename, newVersion, newRevision)

Update a conf.py file to use the new verison.

src.dev.documentation.isIncluded(path)

Return whether the given path should be included in the API.

Parameters :

path : str

The absolute path of the file to check.

Returns :

bool :

Whether the path should be included in the API generation (i.e. whether it does not start with a member of the EXCLUSIONS module constant).

src.dev.documentation.compileAPI(newVersion=None)

Read through src/ and generate an API; update the version.

Recursively scan through the main source code folder of the project and construct code for the documented packages and modules. Treat any folder which contains an __init__.py as a package, and treat all items with a ”.py” extension in such a folder as modules. From each package, create a list of sub-packages and modules and from each module extract a list of classes and functions, constructing reST documentation as appropriate.

src.dev.documentation.compileManual(newVersion=None)

Compile the manual’s reST sources into a PDF and HTML Help files.

src.dev.documentation.compileDocumentation(newVersion=None, api=True, manual=True)

Update software documentation.

Parameters :

newVersion : str

The new version for the documentation. If None (the default), the version string in the Sphinx configuration files will not be changed.

api : bool

Whether to update the API. The default is True.

manual : bool

Whether to update the manual. The default is True.