As is documented in click here, the docstrings for click commands are expected to contain \b characters before a paragraph which should not be made to wrap.
This allows better formatting of docstrings in the help output, without this it is impossible to make any kind of formatting of the help such as point form lists which describe the meaning of each click.Choice() option.
This works well for click's help output, but is also broken for the sphinx-click generated html docs, and for sphinx-man generated man pages.
Here are two examples to show the brokenness:
Broken man page output
NAME
bst-show - Show elements in the pipeline
SYNOPSIS
bst show [OPTIONS] TARGET
DESCRIPTION
Show elements in the pipeline
By default this will only show the specified element, use the --deps option to show an entire pipeline.
FORMAT ~~~~~~ The --format option controls what should be printed for each element, the following symbols can be used in the format string:
%{name} The element name
%{key} The abbreviated cache key (if all sources are consistent)
%{full-key} The full cache key (if all sources are consistent)
%{state} cached, buildable, waiting or inconsistent
%{config} The element configuration
%{vars} Variable configuration
%{env} Environment settings
%{public} Public domain data
The value of the %{symbol} without the leading '%' character is understood as a pythonic formatting string, so python formatting features apply, examle:
build-stream show target.bst --format 'Name: %{name: ^20} Key: %{key: ^8} State: %{state}'
If you want to use a newline in a format string in bash, use the '$' modifier:
build-stream show target.bst --format $'---------- %{name} ----------1{vars}'
OPTIONS
-d, --deps [all|build|run]
Optionally specify a dependency scope to show
--order [stage|alpha]
Staging or alphabetic ordering of dependencies
-f, --format FORMAT
Format string for each element
-a, --arch TEXT
The target architecture (default: x86_64)
--variant TEXT
A variant of the specified target
09-May-2017 BST SHOW(1)
Well formatted output of bst show --help
Usage: bst show [OPTIONS] TARGET
Show elements in the pipeline
By default this will only show the specified element, use the --deps
option to show an entire pipeline.
FORMAT
~~~~~~
The --format option controls what should be printed for each element,
the following symbols can be used in the format string:
%{name} The element name
%{key} The abbreviated cache key (if all sources are consistent)
%{full-key} The full cache key (if all sources are consistent)
%{state} cached, buildable, waiting or inconsistent
%{config} The element configuration
%{vars} Variable configuration
%{env} Environment settings
%{public} Public domain data
The value of the %{symbol} without the leading '%' character is understood
as a pythonic formatting string, so python formatting features apply,
examle:
build-stream show target.bst --format \
'Name: %{name: ^20} Key: %{key: ^8} State: %{state}'
If you want to use a newline in a format string in bash, use the '$'
modifier:
build-stream show target.bst --format \
$'---------- %{name} ----------\n%{vars}'
Options:
-d, --deps [all|build|run] Optionally specify a dependency scope to show
--order [stage|alpha] Staging or alphabetic ordering of dependencies
-f, --format FORMAT Format string for each element
-a, --arch TEXT The target architecture (default: x86_64)
--variant TEXT A variant of the specified target
--help Show this message and exit.
As is documented in click here, the docstrings for click commands are expected to contain
\bcharacters before a paragraph which should not be made to wrap.This allows better formatting of docstrings in the help output, without this it is impossible to make any kind of formatting of the help such as point form lists which describe the meaning of each click.Choice() option.
This works well for click's help output, but is also broken for the sphinx-click generated html docs, and for sphinx-man generated man pages.
Here are two examples to show the brokenness:
Broken man page output
Well formatted output of
bst show --help