API Reference¶

Sphinx extension to display a selection of highlights from a Python library.

Classes:

SphinxHighlightsDirective(name, arguments, …)

Provides the api-highlights directive.

Functions:

`copy_assets`(app[, exception])	Copy asset files to the output.
`format_parameter`(param)	Format an `inspect.Parameter`, for insertion into the highlight panel.
`format_signature`(obj)	Format the signature of the given object, for insertion into the highlight panel.
`get_random_sample`(items)	Returns four random elements from `items`.
`setup`(app)	Setup `sphinx_highlights`.

class SphinxHighlightsDirective(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)[source]¶

Bases: SphinxDirective

Provides the api-highlights directive.

Methods:

`delimited_get`(option, default)	Returns the value of the option with the given name, splitting the input at commas, semicolons and spaces.
`run`()	Create the highlights node.
`run_generic`()	Generate generic reStructuredText output.
`run_html`()	Generate output for `HTML` builders.

delimited_get(option, default)[source]¶

Returns the value of the option with the given name, splitting the input at commas, semicolons and spaces.

Parameters

option (str) – The option name.
default (str) – The default value, as a string separated by commas, spaces or semicolons.

Return type

Iterator[str]

run()[source]¶

Create the highlights node.

Return type: List[Node]

run_generic()[source]¶

Generate generic reStructuredText output.

Return type: List[Node]

run_html()[source]¶

Generate output for HTML builders.

Return type: List[Node]

copy_assets(app, exception=None)[source]¶

Copy asset files to the output.

Parameters

app (Sphinx) – The Sphinx application.
exception (Optional[Exception]) – Any exception which occurred and caused Sphinx to abort. Default None.

format_parameter(param)[source]¶

Format an inspect.Parameter, for insertion into the highlight panel.

Parameters: param (Parameter)
Return type: str
Returns: The reStructuredText string.

format_signature(obj)[source]¶

Format the signature of the given object, for insertion into the highlight panel.

Parameters: obj (Union[type, FunctionType])
Return type: StringList
Returns: A list of reStructuredText lines.

get_random_sample(items)[source]¶

Returns four random elements from items.

Parameters: items (Iterable[~_T])
Return type: List[~_T]

setup(app)[source]¶

Setup sphinx_highlights.

Parameters: app (Sphinx) – The Sphinx application.
Return type: SphinxExtMetadata