plastid.util.scriptlib.help_formatters module

This module contains post-processors that reformats module docstrings for use as command-line script help, by removing rich formatting, substitutions, reStructuredText markup, and some numpydoc tokens.

See also

re

Python regular expressions module

reStructuredText

Specification for reStructuredText, a markup language used by the Sphinx documentation engine, and used throughout the docstrings found in this package

numpydoc

A docstring standard and Sphinx extension that converts human-readable docstrings into valid reStructuredText

plastid.util.scriptlib.help_formatters.format_module_docstring(inp)[source]

Pretty prints module docstrings for use in command-line help, by removing some reStructuredText markup, truncating the docstring at the first numpydoc token, and surrounding help text with separators.

Parameters
inpmulti-line str

Module docstring to format

Returns
str

Formatted docstring

plastid.util.scriptlib.help_formatters.shorten_help(inp)[source]

Pretty prints numpydoc-formatted module, class, or function docstrings for use in command-line help, by removing some reStructuredText markup, and truncating the docstring at the appropriate numpydoc tokens.

Parameters
inpmulti-line str

Class or function docstring to format

Returns
str

Cleaned helptext

RegEx pattern that matches reStructuredText link references of forms `Linkname`_ and `Link text <url>`_

plastid.util.scriptlib.help_formatters.pyrst_pattern = re.compile('(?P<spacing>^|\\s+)(?::(?P<domain>[^:`<>]+))?:(?P<role>[^:`]*):`(?P<argument>[^`<>]+)(?: +<(?P<pointer>[^`]+)>)?`')

RegEx pattern that detects reStructuredText markup of python tokens of the form :domain:role:`argument` or simply :role:`argument`, if the token is preceded by whitespace or begins a line.

Retrieves domain, role, and argument as named attributes if pyrst_pattern.groupdict() is called.

plastid.util.scriptlib.help_formatters.subst_pattern = re.compile('\\|([^|]*)\\|')

RegEx pattern that matches reStructuredText substitution tokens of form |substitution|