documentation module

documentation – Build <doc> tree from in-code doc-strings & .rst files.

usage:documentation.py [-hbdfmwv] [–help] [–builder <format>] [–developer] [–force] [–make] [–warnings] [–version] [<doc-root>]

Authors:

Michael S. Chapman <chapmami@ohsu.edu>,

Oregon Health & Science University

Version:

0.5, March 23, 2016

Changed in version 2/4/15: Started

In the following steps, builds the documentation in a directory here called doc that is distinct from the src directory containing code sources:

• Establishes folder structure under doc, including /build whose

  directories will contain formatted versions of the documentation and /source that will contain mostly .rst files from which the documentation is built. (Uses sphinx-quickstart.)

• Copies .rst files from src into doc.

• Extracts from src python modules, doc-strings that are to be included in

  calling program .rst.

• Saves the output of in-program help listings for inclusion in program

  .rst files.

• Extracts python doc-strings from src scripts and modules (using

  sphinx-apidoc) to make .rst files that are saved in doc.

• Builds the formatted documentation from the .rst files in that have been

  put in doc/source (using sphinx-build as called from make).

Warning

Have not been able to resolve numerous (~35) warnings about (a) lists that end without a blank line; unexpected unindent; (b) duplicate citations (within doc-strings that are extracted for inclusion in other .rst);

Warning

Autodoc is not automatically descending directories as I don’t have the configuration right for the python imports. Not a problem at the moment.

class documentation.Arguments(imports=[], main=True, *args, **kwargs)

Bases: argparser.ArgumentParser

Subclass, adding program-specific command-line options.

Parameters:

• imports ((list of) ArgumentParser method(s)) – method(s) adding arguments to ArgumentParser instance. (Alternative to ArgumentParser parents w/ better maintained groups.)
• main (bool) – Parser for main program (i.e. not listed within an ArgumentParser parents argument). Adds default program information.

static export()

Adding options used in both stand-alone and imported modes.

class documentation.Module(name)

Bases: object

An external python module to be run or interrogated.

Parameters:name (str) – module name

explain()

Help for each command as reStructured literals, split into specific program commands & utilities :return: output of name> help -rl :rtype: str, str

help()

Module’s command-line help as a reStructured literal :return: output of name -h :rtype: str

list()

Module’s command-list as a reStructured literal :return: output of name> help :rtype: str

documentation.apidoc()

Parse in-code src/module doc-strings into .rst files; uses sphinx-apidoc.

documentation.checkfiles()

Check for file clobbering etc..

Returns:whether directory structure appears to be in place Return type:bool

documentation.copyrst(index=False)

Copy .rst files from src directory to source/ in doc directory.

Parameters:index (bool) – Copy index.rst, or exclude; as done by sphinx-quickstart.

documentation.directory_setup()

Runs sphinx-quickstart to set up directory structure.

documentation.epy2rst(text)

Crude/Approx conversion of epytext into reStructured

..deprecated:: 0.5.0 Should not have to repeat initial translation.

documentation.extract()

Extract module strings designed to be included in calling program .rst

documentation.help()

Capture in-program help for inclusion in program .rst files.

documentation.homepage()

Edit source/index.rst in-place.

documentation.make()

documentation.nested_help(text, marker='=-^"_~%', entry=0)

Reformats nested help from Cmd2nest, incl. cascading sections & newlines

Parameters:

• text (str) – text to be converted.
• marker (str) – characters defining cascading output section levels; should match any parent document; default starts w/ the 6 levels used to document Python.
• entry (int) – section level at which to start

Returns:

reStructured text

Return type:

str

documentation.startup()

Program initialization, reading options etc..

Returns:parser Return type:Arguments.ArgumentParser

documentation.translate()

documentation.unpackage()

Temporarily change src from a package to a regular directory.

This will ensure that scripts and module documentation in src appear at top level. Eclipse PyDev requires the top level to be a package, so unless __init__.py(c) are renamed by unpackage, everything will be documented as if in package src.