cape.dkit.modutils: Module docstring utils for DataKit

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.dkit.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.dkit.modutils

pymod

cape.dkit.modutils

relative_file

cape/dkit/modutils.py
cape.dkit.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.dkit.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.dkit.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:
Versions:

  • 2019-12-27 @ddalle: First version

cape.dkit.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()