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

example: documentation.py –clobber –developer –warnings –nonstop –builder=html –builder=latexpdf <desination>

will create html and pdf documentation in the html and latex subdirectories of <destination>/build

Module author: Michael S. Chapman <chapmanms@missouri.edu>

Authors:

Michael S. Chapman <chapmanms@missouri.edu>

Oregon Health & Science University & University of Missouri

Version:

1, Nov 26, 2024

Changed in version 2/4/15: Started

Changed in version 1.0.0: 11/17/20 Python 2.7 –> 3.6

Changed in version 1.0.0a: 11/30/20 subprocess refactoring Popen to run.

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

If reinitializing, save any custom versions of conf.py, index.rst and contents.rst as they will be over-written.

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.

Todo

beyond python 3.7, replace stdout=subprocess.PIPE with capture_output=True

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

Bases: Arguments

Manager for command-line arguments from main and imported modules.

This is a template to be copied into modules, for the handling of command- line options, and would appear something like: class Arguments(argparser.Arguments).

methods export(), domestic() & (optionally) finalize() should be overridden by the module subclass with declarations of the command-line arguments needed by the module.

Parameters:

• imports ((list of) ArgumentParser(s)) – (list of) module(s) from which to obtain “parent” ArgumentParser objects for inclusion.

• main (bool|NoneType) – Add information and arguments appropriate for a main program (or not); if None, will determine by whether this class is defined in __main__.

domestic()

Defines options used only when main program and not when imported.

This method should only be called from a __main__ program, and should instantiate an argparser.ArgumentParser object and populate it with the arguments available (only) when used as a main program. Code after the “pass” can optionally be deleted if never used as a main program.

export()

Defines 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(marker='#*=-^"_~%', entry=2, verbose=False)

Help for program commands, sub-commands with cascading header levels

Parameters:

• 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:

output of name> help -rl

Return type:

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()

Ensure configuration and directory structure, running sphinx-quickstart as needed.

Returns:

ready to go; else sphinx-quickstart is needed.

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 selected module doc-strings for inclusion in calling program .rst

This includes general documentation about the command interpreter, how atoms can be selected / designated, how atomic models can be parameterized for optimization and how symmetry is specified.

documentation.help()

Capture command-line & in-program help for inclusion in program .rst files.

Loops over modules that are run as main programs, capturing help on command line options and, when applicable, on cmd2 program command control, autogenerating .rst files for inclusion in the documentation for each program.

documentation.main()

documentation.make(builder='builder')

Make the sphinx-created Makefile for an html document set.

Parameters:

builder (str) – from the list of formats in builders

https://www.sphinx-doc.org/en/master/man/sphinx-build.html

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.