Reference
The public API of sphinx-codeautolink consists mostly of the configuration
and directives made available to Sphinx.
The extension is enabled with the name sphinx_codeautolink
.
During the build phase, a cache containing code example information is saved
to the Sphinx doctree directory to track references during partial builds.
Configuration
- codeautolink_autodoc_inject
Type:
bool
. Inject aautolink-examples
table to the end of all autodoc definitions. Defaults toFalse
.
- codeautolink_global_preface
Type:
str
. Include aautolink-preface
before all blocks. When other prefaces or concatenated sources are used in a block, the global preface is included first and only once.
- codeautolink_concat_default
Type:
bool
. Default behavior for code block concatenation (seeautolink-concat
). Value corresponds to the “on” and “off” settings in the directive. Defaults toFalse
.
- codeautolink_custom_blocks
Type:
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.
- codeautolink_search_css_classes
Type:
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 tobs4.BeautifulSoup.find_all
.
- codeautolink_inventory_map
Type:
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__module__
.
- codeautolink_warn_on_missing_inventory
Type:
bool
. Warn when an object cannot be found in the inventory (autodoc or intersphinx). Defaults toFalse
.
- codeautolink_warn_on_failed_resolve
Type:
bool
. Warn when failing to resolve the canonical location of an object that a code element references. Defaults toFalse
.
- codeautolink_warn_on_no_backreference
Type:
bool
. Warn when no backreference could be found from reference documentation using theautolink-examples
table. This highlights objects for which no tutorial, example or how-to exists. Defaults toFalse
.
- codeautolink_warn_on_default_parse_fail
Type:
bool
. Warn when a code block using thedefault
lexer cannot be parsed as Python. By default these cases are ignored by the syntax highlighter, so we match the behavior. Defaults toFalse
.
Directives
- .. autolink-examples:: object
Insert a table containing links to sections that reference
object
in their code examples. The table is removed if it would be empty.Options
- :type: (object's reference type, single value)
The object’s reference type as used in other RST roles, e.g.
:func:`function`
.type
is “class” by default, which seems to work for other types as well.
- :collapse: (no value)
Make the table collapsible (using a “details” HTML tag).
- .. autolink-concat:: [mode]
Toggle 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_default
is 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
- .. autolink-preface:: [code]
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.
- .. autolink-skip:: [level]
Skip sphinx-codeautolink functionality.
level
, if specified, must be one of:“next” - next encountered 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. “Next” doesn’t need to be specified right before the block that would consume it. For e.g. literal blocks the skip directive would be inserted before the preceding paragraph.
CSS class
The CSS class used in all code block links is sphinx-codeautolink-a
.
By default, the links only have a light blue hover colour.
The style has been made more obvious in the documentation for demonstration.
See Custom link styles for more information.
Cleanup functions
The functions below are usable for cleaning
pycon
and ipython
code blocks.
They are intended to be used with codeautolink_custom_blocks
.
- sphinx_codeautolink.clean_pycon(source)
Clean up Python console syntax to pure Python.
Warning types
Sphinx logging machinery is used to issue warnings during documentation builds.
All warning subtypes below are in the codeautolink.*
namespace
and can be ignored with configuring suppress_warnings
.
invalid_argument
: issued when a directive is used incorrectlyclean_block
: issued when cleaning a block fails with aSyntaxError
parse_block
: issued when parsing a block fails with aSyntaxError
import_star
: issued when a library cannot be imported to determine the names that animport *
would introducematch_block
: issued when a block cannot be matchedmatch_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 inventoryfailed_resolve
: issued when an object’s canonical location in a module cannot be determined