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.[source][source][source]

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/ for the original implementation.

class DummyConfig[source]
text_newlines = '\n'
text_sectionchars = '*=-~"+`'

alias of DummyConfig

DummyTextBuilder.translator_class = None
class*args, **kwargs)[source]

Bases: argparse.RawDescriptionHelpFormatter

_split_lines(text, width)[source]
class, builder)[source]

Bases: sphinx.writers.text.TextTranslator

visit_literal(node)[source], rawtext, text, lineno, inliner, options=None, context=None)[source]

Format :doc: roles, used to reference another bits of documentation., width=None, line_prefix=' ')[source]

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.

  • 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).

formatted docstring.[source]

Generate and format help for an evaluation context of a module. Looks for context content, and gives it a nice header, suitable for command-line help, applying formatting along the way.

Parameters:source (gluetool.glue.Configurable) – object whose eval context help we should format.
Returns:Formatted help., logger=None)[source]

Extract information of evaluation context content from the source - a module or any other object with eval_context property. The information we’re looking for is represented by an assignment to special variable, __content__, in the body of eval_context getter. __content__ is expected to be assigned a dictionary, listing context variables (keys) and their descriptions (values).

If it’s not possible to find such information, or an exception is raised, the function returns an empty dictionary.

Parameters:source (gluetool.glue.Configurable) – object to extract information from.
Return type:dict(str, str), name=None)[source]

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

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

(signature, body) pair.[source]

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.[source]

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., rawtext, text, lineno, inliner, options=None, content=None)[source]

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

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

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

Quoting PEP 257 <>:

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.