cape.tnakit.modutils: Module documentation utilities

This module provides utilities for documenting other modules, with some simple examples demonstrated within the docstring of this file. Its primary purpose is to provide more information in the docstring of a module with some automated macros.

Because this functionality is most useful within a module, so that the docstring can be modified during import, the usual use case requires the special parameters __file__, __name__, and of course __doc__.

import cape.tnakit.modutils as modutils

__doc__ = modutils.rst_docstring(__name__, __file__, __doc__)

See rst_docstring() for more details on how this works and all of the options and expansions that it can perform. The table below shows some examples as they expand for this module.

Pattern	Result
file	modutils.py
mod	cape.tnakit.modutils
pymod	cape.tnakit.modutils
relative_file	cape/tnakit/modutils.py

cape.tnakit.modutils.list_modnames(fname, basename='', maxdepth=2, depth=0)

Create a list of lists of submodules from fname

Call:

>>> modnamelist = list_modnames(fname, basename="", **kw)

Inputs:

fname: str

Name of (Python module) file from which list is started

basename: {""} | str

Module name to serve as prefix

maxdepth: {2} | None | int >= 0

Maximum number of sublevels

depth: {0} | int >= 0

Current depth

Outputs:

modnamelist: list[str]

List of module names, with "."

Versions:

• 2020-01-14 @ddalle: First version

cape.tnakit.modutils.list_modules(fname, maxdepth=2, depth=0)

Create a list of lists of submodules from fname

Call:

>>> modlist = list_modules(fname, maxdepth=2, depth=0)

Inputs:

fname: str

Name of (Python module) file from which list is started

maxdepth: {2} | None | int >= 0

Maximum number of sublevels

depth: {0} | int >= 0

Current depth

Outputs:

modlist: list[str | list]

Recursive list of module names

Versions:

• 2019-12-27 @ddalle: First version

cape.tnakit.modutils.rst_docstring(modname, modfile, doc, meta=None, **kw)

Modify a docstring with automatic expansions

Replacements are made to doc such that %(file)s is replaced with the file name (without path) of the module file as inferred from modfile. The full table of replacement patterns recognized by default is below. Note that the hline and hline_after parameters can specify the character to use for the horizontal line as long as it is a valid reST separator character.

absfile	Absolute path to modfile
file	File name (without path) of module
hline-	Create title line with length of the preceding line using - as character
hline=	Create title line with length of the preceding line using = as character
hline_after-	Create title line with length of the following line using - as character
meta	Convert meta dict to reST string
mod	Full name of module with reST decorations
pymod	Full name of module without markup
relative_file	Relative file name inferred from modname
submodules	Search folder and find all submodules up to maxdepth levels; only if file is __init__.py

Additional replacement patterns can be specified in kw; if the value is not a string, it will be converted to reST text using cape.tnakit.rstutils.py2rst().

Call:

>>> txt = rst_docstring(modname, modfile, doc, meta=None, **kw)

Inputs:

modname: str

Name of module, usually from mod.__name__

modfile: str

Module file name, usually from mod.__file__

doc: str

Raw docstring with to expand, from mod.__doc__

meta: {None} | dict | str

Expansion information for %(meta)s pattern

maxdepth: {2} | int | None

Maximum depth for submodules macro

kw: dict

Expansions for additional macros

See Also:

• cape.tnakit.modutils

• cape.tnakit.rstutils.py2rst()

Versions:

• 2019-12-27 @ddalle: First version

cape.tnakit.modutils.rst_submodules(modname, modfile, indent=4, maxdepth=2, **kw)

Create a bullet list of submodules from folder of fname

Call:

>>> txt = rst_submodules(modname, modfile, **kw)

Inputs:

modname: str

Name of the module as imported in Python

modfile: str

Name of (Python module) file from which list is started

indent: {4} | int > 0

Number of white spaces at the beginning of line

maxdepth: {2} | None | int >= 0

Maximum number of sublevels

tab: {4} | int > 0

Number of additional spaces in an indentation

depth: {0} | int >= 0

Current depth level (for recursion)

prefix: {""} | str

Prefix to add to each module’s name (mostly for recursion)

Outputs:

txt: str

RST-formatted outline

Versions:

• 2018-07-03 @ddalle: First version

• 2019-12-27 @ddalle: Split part to list_modules()