documentation_summary

Allows insertion of a summary line on the title page generated with the LaTeX builder, and at a custom location throughout the document.

New in version 2.2.0.

Enable sphinx_toolbox.documentation_summary by adding the following to the extensions variable in your conf.py:

extensions = [
    ...
    'sphinx_toolbox.documentation_summary',
    ]

For more information see https://www.sphinx-doc.org/en/master/usage/extensions#third-party-extensions .

Configuration

documentation_summary
Type: str

The documentation summary to display on the title page with the LaTeX builder, and at the location of documentation-summary directives for other builders.

If undefined no summary is shown.

Usage

.. documentation-summary::

Adds the documentation summary as configured above.

Example

.. documentation-summary::

Box of handy tools for Sphinx 🧰 📔

:meta:

Include the summary as a meta “description” tag in the HTML output.

The structure of the description is {project} -- {summary}, where project is configured in conf.py.

See the sphinx documentation for more information on the project option.

New in version 2.10.0.

API Reference

Classes:

DocumentationSummaryDirective(name, …)

A Sphinx directive for creating a summary line.

Functions:

configure(app, config)

Configure sphinx_toolbox.documentation_summary.

setup(app)

Setup sphinx_toolbox.documentation_summary.

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

Bases: SphinxDirective

A Sphinx directive for creating a summary line.

Methods:

run()

Process the content of the directive.

run()[source]

Process the content of the directive.

Return type

List[Node]

configure(app, config)[source]

Configure sphinx_toolbox.documentation_summary.

Parameters
  • app (Sphinx) – The Sphinx application.

  • config (Config)

setup(app)[source]

Setup sphinx_toolbox.documentation_summary.

Parameters

app (Sphinx) – The Sphinx application.

Return type

SphinxExtMetadata