gluetool.help module

Command-line --help helpers (muhaha!).

gluetool uses docstrings to generate help for command-line options, modules, shared functions and other stuff. To generate good looking and useful help texts a bit of work is required. Add the Sphinx which we use to generate nice documentation of gluetool‘s API and structures, with its directives, and it’s even more work to make readable output. Therefore these helpers, separated in their own file to keep things clean.

gluetool.help.C_ARGNAME(text)

gluetool.help.C_FUNCNAME(text)

gluetool.help.C_LITERAL(text)

class gluetool.help.DummyTextBuilder

Sphinx TextWriter (and other writers as well) requires an instance of Builder class that brings configuration into the rendering process. The original TextBuilder requires Sphinx application which brings a lot of other dependencies (e.g. source paths and similar stuff) which are impractical in our use case (“render short string to plain text”). Therefore this dummy class which just provides minimal configuration - TextWriter requires nothing else from Builder instance.

See sphinx/writers/text.py for the original implementation.

class DummyConfig

text_newlines = '\n'

text_sectionchars = '*=-~"+`'

DummyTextBuilder.config

alias of DummyConfig

DummyTextBuilder.translator_class = None

class gluetool.help.LineWrapRawTextHelpFormatter(*args, **kwargs)

Bases: argparse.RawDescriptionHelpFormatter

_split_lines(text, width)

class gluetool.help.TextTranslator(document, builder)

Bases: sphinx.writers.text.TextTranslator

depart_field_name(node)

depart_literal(node)

visit_field_name(node)

visit_literal(node)

gluetool.help.docstring_to_help(docstring, width=None, line_prefix=' ')

Given docstring, process and render it as a plain text. This conversion function is used to generate nice and readable help strings used when printing help on command line.

Parameters:

• docstring (str) – raw docstring of Python object (function, method, module, etc.).
• width (int) – Maximal line width allowed.
• line_prefix (str) – prefix each line with this string (e.g. to indent it with few spaces or tabs).

Returns:

formatted docstring.

gluetool.help.function_help(func, name=None)

Uses function’s signature and docstring to generate a plain text help describing the function.

Parameters:

• func (callable) – Function to generate help for.
• name (str) – If not set, func.__name__ is used by default.

Returns:

(signature, body) pair.

gluetool.help.functions_help(functions)

Generate help for a set of functions.

Parameters:callable) functions (list(str,) – Functions to generate help for, passed as name and the corresponding callable pairs. Return type:str Returns:Formatted help.

gluetool.help.option_help(txt)

Given option help text, format it to be more suitable for command-line help. Options can provide a single line of text, or mutiple lines (using triple quotes and docstring-like indentation).

Parameters:txt (str) – Raw option help text. Returns:Formatted option help text.

gluetool.help.py_default_role(role, rawtext, text, lineno, inliner, options=None, content=None)

Default handler we use for py:... roles, translates text to literal node.

gluetool.help.rst_to_text(text)

Render given text, written with RST, as plain text.

Parameters:text (str) – string to render. Return type:str Returns:plain text representation of text.

gluetool.help.trim_docstring(docstring)

Quoting PEP 257 <https://www.python.org/dev/peps/pep-0257/#handling-docstring-indentation>:

Docstring processing tools will strip a uniform amount of indentation from the second and further lines of the docstring, equal to the minimum indentation of all non-blank lines after the first line. Any indentation in the first line of the docstring (i.e., up to the first newline) is insignificant and removed. Relative indentation of later lines in the docstring is retained. Blank lines should be removed from the beginning and end of the docstring.

Code bellow follows the quote.

This method does exactly that, therefore we can keep properly aligned docstrings while still use them for reasonably formatted help texts.

Parameters:docstring (str) – raw docstring. Return type:str Returns:docstring with lines stripped of leading whitespace.