def usage_message_callback(app, what, name, obj, options, lines):
"""
Reformat human friendly usage messages to reStructuredText_.
Refer to :func:`enable_usage_formatting()` to enable the use of this
function (you probably don't want to call :func:`usage_message_callback()`
directly).
This function implements a callback for ``autodoc-process-docstring`` that
reformats module docstrings using :func:`.render_usage()` so that Sphinx
doesn't mangle usage messages that were written to be human readable
instead of machine readable. Only module docstrings whose first line starts
with :data:`.USAGE_MARKER` are reformatted.
The parameters expected by this function are those defined for Sphinx event
callback functions (i.e. I'm not going to document them here :-).
"""
# Make sure we only modify the docstrings of modules.
if isinstance(obj, types.ModuleType) and lines:
# Make sure we only modify docstrings containing a usage message.
if lines[0].startswith(USAGE_MARKER):
# Convert the usage message to reStructuredText.
text = render_usage('\n'.join(lines))
# Clear the existing line buffer.
while lines:
lines.pop()
# Fill up the buffer with our modified docstring.
lines.extend(text.splitlines())
def test_render_usage(self):
assert render_usage("Usage: some-command WITH ARGS") == "**Usage:** `some-command WITH ARGS`"
assert render_usage("Supported options:") == "**Supported options:**"
assert 'code-block' in render_usage(dedent("""
Here comes a shell command:
$ echo test
test
"""))
assert all(token in render_usage("""
Supported options:
-n, --dry-run
Don't change anything.
""") for token in ('`-n`', '`--dry-run`'))
def usage_message_callback(app, what, name, obj, options, lines):
"""
Reformat human friendly usage messages to reStructuredText_.
Refer to :func:`enable_usage_formatting()` to enable the use of this
function (you probably don't want to call :func:`usage_message_callback()`
directly).
This function implements a callback for ``autodoc-process-docstring`` that
reformats module docstrings using :func:`.render_usage()` so that Sphinx
doesn't mangle usage messages that were written to be human readable
instead of machine readable. Only module docstrings whose first line starts
with :data:`.USAGE_MARKER` are reformatted.
The parameters expected by this function are those defined for Sphinx event
callback functions (i.e. I'm not going to document them here :-).
"""
# Make sure we only modify the docstrings of modules.
if isinstance(obj, types.ModuleType) and lines:
# Make sure we only modify docstrings containing a usage message.
if lines[0].startswith(USAGE_MARKER):
# Convert the usage message to reStructuredText.
text = render_usage('\n'.join(lines))
# Clear the existing line buffer.
while lines:
lines.pop()
# Fill up the buffer with our modified docstring.
lines.extend(text.splitlines())
def test_render_usage(self):
"""Test :func:`humanfriendly.usage.render_usage()`."""
assert render_usage("Usage: some-command WITH ARGS") == "**Usage:** `some-command WITH ARGS`"
assert render_usage("Supported options:") == "**Supported options:**"
assert 'code-block' in render_usage(dedent("""
Here comes a shell command:
$ echo test
test
"""))
assert all(token in render_usage(dedent("""
Supported options:
-n, --dry-run
Don't change anything.
""")) for token in ('`-n`', '`--dry-run`'))