Package topo :: Package misc :: Module gendocs

Module gendocs

Topographica-specific changes to the standard pydoc command.

Moves generated pydoc HTML files to the docs directory after they are created by pydoc. Intended for use with MAKE, from within the base topographica/ directory.

The generated index.html file is for the topo/__init__.py file, which does not necessarily catalog every .py file in topo/. To see all files, select the 'index' link at the top of one of the html docs.

To generate documentation, enter 'make docs' from the base topographica/ directory, which will call this file on the Topographica sources.

From the Makefile (Tabs have been stripped):

cleandocs:
    - rm -r docs

docs: topo/*.py
    mkdir -p docs
    ./topographica topo/gendocs.py
    mv docs/topo.__init__.html docs/index.html

$Id: gendocs.py 4546 2007-01-04 16:55:33Z jbednar $

Version: $Revision: 4546 $

Functions

[hide private]

_file_list(base_name)
Recursively generate a list of files and directories to document.

source code

filename_to_docname(f)
Convert a path name into the PyDoc filename it will turn into.

source code

filename_to_packagename(f)
Convert a path name into the Python dotted-notation package name.

source code

generate_docs()
Generate all pydoc documentation files within a docs directory under ./topographica according to the constant DOCS.

source code

Variables

[hide private]

TOPO = 'topo'

DOCS = 'doc/Reference_Manual'

Function Details

[hide private]

_file_list(base_name)

source code

Recursively generate a list of files and directories to document.

base_name is the relative path to add to directories and files. Files that match CVS or __init__.py are ignored.

filename_to_docname(f)

source code

Convert a path name into the PyDoc filename it will turn into.

If the path name ends in a .py, then it is cut off. If there is no extension, the name is assumed to be a directory.

filename_to_packagename(f)

source code

Convert a path name into the Python dotted-notation package name.

If the name ends in a .py, then cut it off. If there is no extension, the name is assumed to be a directory, and nothing is done other than to replace the '/' with '.'

generate_docs()

source code

Generate all pydoc documentation files within a docs directory under ./topographica according to the constant DOCS. After generation, there is an index.html that displays all the modules. Note that if the documentation is being changed, it may be necessary to call 'make cleandocs' to force a regeneration of documentation. (We don't want to regenerate all the documentation each time a source file is changed.)