sphinx-evita documentation¶

Sphinx plugins and theme customizations for the EVITA project.

Purpose¶

This package includes customizations primarily meant for authoring modules in the EVITA project. The implementation is however general purpose and maybe reused for any project, which uses:

sphinx-lesson based markup for writing content, and
furo as the theme

Installation¶

Install into your python environment with:

pip install sphinx-evita

Then in the Sphinx conf.py file add:

...
extensions = [
    # other extensions
    "sphinx_evita",
]

Note

The official EVITA template is pre-configured to use this.

Implementation¶

The main powerhorse of this extension is sphinx_evita.setup(). It does the following:

Connects the sphinx_evita.init_static_path() function to the builder-inited event. This ensures that static files (like CSS or JavaScript) are properly linked when the HTML page loads.
Sets up three sub-extensions:
- sphinx_evita.pdfembed: exposes the pdfembed directive.
- sphinx_evita.directives: defines some more custom Sphinx directives for the extension.
- sphinx_evita.css: links extra CSS stylesheets.
Checks if the current project is an EVITA project using the sphinx_evita.hooks.is_evita_project() function. If it is, it configures branding and theme settings by connecting the sphinx_evita.hooks.config_branding() and sphinx_evita.hooks.config_theme() functions to the config-inited event. If not, it logs a warning. Which means that certain conf.py values gets overwritten.

Finally it returns a dictionary with metadata about the extension, including its version and flags indicating that it is safe for parallel reading and writing.

Configuration¶

The extension also declares certain configuration values meant for Sphinx conf.py,

evita_pdfembed_html_tag which defaults to "iframe". This means that an <iframe ...></iframe> HTML tag will be used to embed the PDF. Alternative value is "object" tag which embeds using an <object></object>.

evita_eu_funding_badge: Add EU badge to the page footer. Supported values are "funded", "co-funded", "" (default, empty string). Original files from sourced from here. In the special case where it is detected to be an EVITA project by sphinx_evita.hooks.is_evita_project(), the badge will be set as "funded" automatically.

Contents: