sphinxcontrib.argdoc.ext module

Functions that constitute the sphinxcontrib.argdoc extension for Sphinx.

User functions

noargdoc()

Function decorator that forces sphinxcontrib.argdoc to skip a main-like function it would normally process

Developer functions

format_argparser_as_docstring()

Extract tables of arguments from an ArgumentParser and from all of its subprograms, then format their descriptions and help text.

get_subcommand_tables()

Extract tables from all subcommand ArgumentParsers contained by an enclosing ArgumentParser

post_process_automodule()

Event handler that activates sphinxcontrib.argdoc upon autodoc-process-docstring events

setup()

Register sphinxcontrib.argdoc with the running Sphinx instance

sphinxcontrib.argdoc.ext.safeunicode(inp)

Convert a string to unicode in a Python 2.7/3.x-safe way

Parameters:

inp : str

Input string

Returns:

unicode (Python 2.7) or string (Python 3.x)

utf-8 encoded representation of inp

sphinxcontrib.argdoc.ext.get_patterns(prefix_chars='-')

Retrieve a dictionary of regular expressions that separate argument names from their values and descriptions

Parameters:

prefix_chars : str, optional

String of prefix characters that the ArgumentParser uses (Default: ‘-‘)

Returns:

dict

Dictionary of regular expression patterns

sphinxcontrib.argdoc.ext.get_col1_text(matchdict)

Format argument name(s) and value(s) for column 1 of argument tables

Parameters:

matchdict : dict

Dictionary of values

Returns:

str (unicode if Python 2.7)

sphinxcontrib.argdoc.ext.get_col2_text(matchdict)

Format argument descriptions, if present, for column 2 of argument tables

Parameters:

matchdict : dict

Dictionary of values

Returns:

str (unicode if Python 2.7)

sphinxcontrib.argdoc.ext.make_rest_table(rows, title=False, indent=0)

Make a reStructuredText table from a list of rows of items

Parameters:

rows : list of tuples

A row of text to put in the table, each tuple item a cell

title : bool, optional

If True, the first pair is assumed to contain column headings (Default: False)

indent_size : int, optional

Number of spaces prepend to each line of output (Default: 0)

Returns:

list

List of strings, corresponding to multi-line reStructuredText table

sphinxcontrib.argdoc.ext.format_warning(topline, details)

Format warning text clearly

Parameters:

topline : str

One-line description of warning

details : str

Multiline, detailed description of warning (e.g. exception info)

Returns:

str

Multiline warning message, formatted

sphinxcontrib.argdoc.ext.noargdoc(func)

Decorator that forces sphinxcontrib.argdoc to skip processing of func

Parameters:

func : function

main-like function of a script

Returns:

func

wrapped function

sphinxcontrib.argdoc.ext.get_subcommand_tables(app, obj, help_lines, patterns, start_line, command_chain='', section_head=True, header_level=1)

Process help output from an ArgumentParser that includes one or more subcommands. Called by format_argparser_as_docstring()

Parameters:

app

Sphinx application instance

obj : object

Object (e.g. module, class, function) to document

help_lines : list

List of strings, each corresponding to a line of output from having passed --help as an argument to the main-like function

patterns : dict

Dictionary names of line types in argparse output to regular expression patterns that process those line types

start_line : int

Line in argparse help output containing subcommand header

section_head : bool, optional

If True, a section header for “Command-line arguments” will be included in the output. (Default: True)

pre_args : int, optional

Number of arguments required to be supplied before subcommand help can be retrieved (Default: 0)

header_level : int, optional

Level of header to use for section_name. Lower numbers are higher precedence. (Default: 1)

Returns:

list

List of strings encoding reStructuredText table of command-line arguments for all subprograms in the containing argparser

sphinxcontrib.argdoc.ext.format_argparser_as_docstring(app, obj, help_lines, patterns, section_head=True, section_name=u'Command-line arguments', header_level=1, _is_subcommand=False, command_chain='')

Process help output from an argparse.ArgumentParser. Called by post_process_automodule() and get_subcommand_tables()

Parameters:

app

Sphinx application instance

obj : object

Object (e.g. module, class, function) to document

help_lines : list

List of strings, each corresponding to a line of output from having passed --help as an argument to the main-like function

patterns : dict

Dictionary names of line types in argparse output to regular expression patterns that process those line types

section_head : bool, optional

If True, a section header for “Command-line arguments” will be included. This messes up parsing for function docstrings, but is fine for module docstrings (Default: False).

section_name : str, optional

A name or title for the current program or subcommand. (Default: ‘Command-line arguments’)

header_level : int, optional

Level of header to use for section_name. Lower numbers are higher precedence. (Default: 1)

_is_subcommand : bool, optional

If True, include module docstring in output. Required for subcommands whose help won’t be included by in the module docstring found by autodoc. (Default: False)

Returns:

list

List of strings encoding reStructuredText table of arguments for program or subprogram

sphinxcontrib.argdoc.ext.post_process_automodule(app, what, name, obj, options, lines)

Insert a table listing and describing an executable script’s command-line arguments into its :automodule: documentation.

Any main-like function decorated with the noargdoc() decorator will be skipped. A function is determined to be a main-like function if its name matches the name set in the configuration option argdoc_main_func inside conf.py. The default value for argdoc_main_func is main.

Parameters:

app

Sphinx application instance

what : str

Type of object (e.g. “module”, “function”, “class”)

name : str

Fully-qualified name of object

obj : object

Object (e.g. module, class, function) to document

options : object

Options given to the directive, whose boolean properties are set to True if their corresponding flag was given in the directive

lines : list

List of strings encoding the module docstrings after Sphinx processing

Raises:

:class:`~sphinx.errors.ConfigError`

If argdoc_main_func is defined in conf.py and is not a str

Notes

Per the autodoc spec, this function modifies lines in place.