Additional Extensions¶

Theme and User Interface¶

These extensions provide the visual appearance of the documentation and additional user interface elements.

sphinx_immaterial¶

This extension provides the theme used for the generated documentation website. Compared to many other Sphinx themes, it offers extensive customization options, enhanced navigation, search capabilities, and many additional UI components.

See immaterial template documentation for further information.

sphinx_immaterial.kbd_keys¶

The additional Immaterial extension kbd_keys (keys extension manual) introduces the :keys: role, which can be used to display keyboard shortcuts with styled keycaps.

Examples:

• Enter

• Ctrl+Shift+B

• Alt

- :keys:`Enter`
- :keys:`Ctrl + Shift + B`
- :keys:`Alt`

sphinx_design¶

sphinx_design provides additional directives and components for creating modern, responsive documentation layouts.

Features include:

• Cards

• Grids

• Dropdowns

• Tabs

• Badges

• Buttons

These components can be combined with the selected theme to create visually appealing and well-structured documentation.

Content Authoring¶

These extensions improve content creation and add support for additional content types.

myst_parser¶

This extension enables Markdown support in Sphinx and allows Markdown and reStructuredText files to be used together within the same documentation project. MyST additionally supports many Sphinx-specific features such as directives, roles, cross-references, and admonitions directly in Markdown documents.

See MyST-Parser documentation or the local Markdown syntax section for more information.

sphinx-embedPDF¶

This extension allows PDF files to be embedded directly into the generated documentation.

It provides a convenient directive for displaying PDF documents within a page and includes an additional role for creating links that automatically open in a new browser tab. The extension is especially useful for integrating datasheets, manuals, reports, or other reference documents without requiring users to leave the documentation.

New-tab links¶

The role :ntLink: creates hyperlinks that automatically open in a new browser tab.

Example:

:ntLink:`src:https://www.google.com, name:Google, symbol:True`

Parameters:

• src: URL of the target page.

• name: Text displayed for the link.

• symbol: If set to True, a new-tab icon is displayed next to the link.

Embedded PDFs¶

The embedpdf directive embeds a PDF document directly into the page.

.. embedpdf:: sample.pdf
   :alt: Alternative text shown if the PDF cannot be displayed.
   :name: Embed PDF Sample
   :width: 95
   :ratio: 72

sphinxcontrib.video¶

This extension allows videos to be embedded directly into the documentation. It converts the Sphinx directive into the required HTML video elements during document generation.

.. video:: /_static/images/exampleVideo.mp4
   :autoplay:

See sphinx video documentation for more information.

sphinxcontrib.quizdown¶

The Quizdown extension allows quizzes to be created using a simple Markdown-based syntax.

Quiz definitions can either be written directly in the documentation source file or loaded from an external file. During documentation generation, the content is converted into interactive quizzes.

.. quizdown::

   ---
   primary_color: orange
   secondary_color: lightgray
   text_color: black
   shuffle_questions: false
   ---

   ## What is the capital of Germany?

      > It's the largest city in Germany.

      - [x] Berlin
      - [ ] Cologne
      - [ ] Frankfurt
      - [ ] Munich

   ## Put the [days](https://en.wikipedia.org/wiki/Day) in order!

      > Monday is the **first** day of the week.

      1. Monday
      1. Tuesday
      1. Wednesday
      1. Thursday
      1. Friday
      1. Saturday
      1. Sunday

   ## What are letters in the alphabet?

      > There are multiple answers possible

      - [x] A
      - [x] B
      - [ ] 1
      - [ ] !
      - [ ] 17

See quizdown github page for additional details.

Navigation and Referencing¶

These extensions simplify navigation and cross-referencing within the documentation.

sphinx.ext.autosectionlabel¶

This extension allows section headings to be referenced automatically without creating explicit labels.

The variable autosectionlabel_prefix_document is set to True to ensure that sections with identical names in different documents can still be referenced uniquely.

See autosectionlabel documentation for more information.

Conditional Content¶

These extensions provide mechanisms for controlling which content is included in the generated documentation.

sphinx.ext.ifconfig¶

The ifconfig extension can be used to include or exclude content depending on configuration variables defined in conf.py. A typical use case is enabling or disabling exercises, solutions, or customer-specific documentation sections without modifying the source files.

See ifconfig extension documentation for more information.

Mathematics¶

These extensions provide support for mathematical notation and formulas.

sphinxcontrib.katex¶

This extension enables rendering of mathematical formulas using KaTeX, a fast JavaScript-based math rendering engine.

KaTeX supports most LaTeX mathematical notation and provides significantly faster rendering than MathJax while maintaining high-quality output.

Example:

PDF Generation¶

These extensions provide functionality for generating PDF documents from the documentation.

sphinx_pdf_generate¶

A Sphinx extension that generates individual PDF files for documentation pages.

The extension supports numerous advanced features, including:

• Table of contents generation

• Customizable cover pages

• Support for CSS Paged Media

• Automatic use of Sphinx page metadata for PDF generation

• Per-page PDF export

To generate PDFs for the configured pages, run:

sphinx-pdf-generate <SOURCEDIR> <BUILDDIR>/html

Alternatively:

make pagePDF

See sphinx pdf generate documentation for more information.

Internationalization¶

These extensions support multi-language documentation projects.

sphinx-intl¶

sphinx-intl adds internationalization (i18n) support to Sphinx projects.

It provides utilities for extracting translatable strings, generating translation files, and building documentation in multiple languages. This makes it possible to maintain a single documentation source while generating localized versions for different audiences.

Development Tools¶

These tools simplify the development and maintenance of the documentation.

sphinx-autobuild¶

sphinx-autobuild provides a live-reloading development server for Sphinx documentation.

It automatically monitors source files for changes and rebuilds the documentation whenever a file is modified. The browser is refreshed automatically, making documentation development much faster and more convenient.

Example:

sphinx-autobuild <source> <build/html>

Alternatively:

make autobuild

This tool is intended for local development and testing and is typically not used in CI/CD pipelines.