The public API of sphinx-codeautolink consists mostly of the configuration
and directives made available to Sphinx.
The extension is enabled with the name
During the build phase, a cache containing code example information is saved
to the Sphinx doctree directory to track references during partial builds.
bool. Inject a
autolink-examplestable to the end of all autodoc definitions. Defaults to
str. Include a
autolink-prefacebefore all blocks. When other prefaces or concatenated sources are used in a block, the global preface is included first and only once.
bool. Default behavior for code block concatenation (see
autolink-concat). Value corresponds to the “on” and “off” settings in the directive. Defaults to
Dict[str, None | str | Callable[[str], Tuple[str, str]]]. Register custom parsers for lexers of unknown types of code blocks. They are registered as a dict mapping a block lexer name to a function possibly cleaning up the block content to valid Python syntax. If none is specified, no transformations are applied. A string is interpreted as an importable transformer function. The transformer must return two strings: the code appearing in documentation (often just the original source) and the cleaned Python source code. The transformer must preserve line numbers for correct matching. The transformer may raise a syntax error, which is caught automatically and a corresponding Sphinx warning using subtype “parsing_error” is issued.
List[str]. Extra CSS classes used to search for code examples when matching the final HTML. May contain multiple values separated by spaces as they would be passed to
Dict[str, str]. Remap the final location of any inventory entry. Useful when objects are imported and documented somewhere else than their original location as advertised by
bool. Issue warning when an object cannot be found in the inventory (autodoc or intersphinx). Defaults to
bool. Issue warning when failing to resolve the canonical location of an object that a code element references. Defaults to
Insert a table containing links to sections that reference
objectin their code examples. The table is removed if it would be empty.
The object’s reference type as used in other RST roles, e.g.
typeis “class” by default, which seems to work for other types as well.
Make the table collapsible (using a “details” HTML tag).
Toggle literal block concatenation. Concatenated code blocks are treated as a continuous source, so that imports and statements in previous blocks affect later blocks. Concatenation is begun at the directive, not applied retroactively. The directive also resets concatenation state. Until this directive is encountered,
codeautolink_concat_defaultis used as the default behavior.
mode, if specified, must be one of:
“on” - concatenate all blocks in the current file (default value)
“off” - stop concatenation
“section” - concatenate until the next title, then reset to the previous value (“on” or “off”) also resetting concatenation state
Include a hidden preface in the next code block. The next block consumes this directive even if it is not processed (e.g. non-Python blocks) to avoid placement confusion. A multiline preface can be written in the content portion of the directive. Prefaces are included in block concatenation.
Skip sphinx-codeautolink functionality.
level, if specified, must be one of:
“next” - next block (default)
“section” - blocks until the next title
“file” - all blocks in the current file
“off” - turn skipping off
If “next” was specified, the following block consumes this directive even if it is not processed (e.g. non-Python blocks) to avoid placement confusion. Skipped blocks are ignored in block concatenation as well, and concatenation is resumed without breaks after skipping is over.
The CSS class used in all code block links is
The functions below are usable for cleaning
ipython code blocks.
They are intended to be used with
Clean up Python console syntax to pure Python.
Sphinx logging machinery is used to issue warnings during documentation builds.
All warning subtypes below are in the
and can be ignored with configuring
invalid_argument: issued when a directive is used incorrectly
clean_block: issued when cleaning a block fails with a
parse_block: issued when parsing a block fails with a
import_star: issued when a library cannot be imported to determine the names that an
import *would introduce
match_block: issued when a block cannot be matched
match_name: issued when a code snippet cannot be matched
The following warnings are only issued depending on configuration:
missing_inventory: issued when an object cannot be found in the inventory
failed_resolve: issued when an object’s canonical location in a module cannot be determined