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 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`'))