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.
-
class
gluetool.help.
DummyTextBuilder
[source]¶ Sphinx
TextWriter
(and other writers as well) requires an instance ofBuilder
class that brings configuration into the rendering process. The originalTextBuilder
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 fromBuilder
instance.See
sphinx/writers/text.py
for the original implementation.-
DummyTextBuilder.
config
¶ alias of
DummyConfig
-
DummyTextBuilder.
translator_class
= None¶
-
-
class
gluetool.help.
TextTranslator
(document, builder)[source]¶ Bases:
sphinx.writers.text.TextTranslator
-
gluetool.help.
docstring_to_help
(docstring, 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.
Parameters: Returns: formatted docstring.
-
gluetool.help.
function_help
(func, name=None)[source]¶ Uses function’s signature and docstring to generate a plain text help describing the function.
Parameters: Returns: (signature, body)
pair.
-
gluetool.help.
functions_help
(functions)[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.
-
gluetool.help.
option_help
(txt)[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.
-
gluetool.help.
py_default_role
(role, rawtext, text, lineno, inliner, options=None, content=None)[source]¶ Default handler we use for
py:...
roles, translates text to literal node.
-
gluetool.help.
rst_to_text
(text)[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
.
-
gluetool.help.
trim_docstring
(docstring)[source]¶ 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.