About

This page contains information about used external assets as well as topics that didn’t really fit anywhere else.

Assets

The Sphinx awesome theme relies on the following external assets. For a full list of dependencies, see the file pyproject.toml for Python dependencies and package.json for JavaScript dependencies.

Purpose

Name/Website

License

CSS framework

Tailwind

MIT License

Select and copy stuff

Clipboard.js

MIT License

Fonts

Roboto

Apache License, Version 2.0

Icons

Material icons

Apache License, Version 2.0

Tooltips

Primer/CSS

MIT License

Note: versions ≤ 1.13.1 used these icons instead:

Entypo by Daniel Bruce

Creative Commons Attribution-ShareAlike 4.0

Zondicons by Steve Schoger

?

The icons are copied and included as SVG directly in the HTML templates. The fonts are bundled in the theme’s static directory. The CSS for the tooltips was copied into the file tooltips.css and adapted to use Tailwind’s classes where feasible.

How does it work?

Sphinx themes are a collection of HTML templates, CSS styles and JavaScript files. Sphinx uses the Jinja2 templating language. The main template is in the file layout.html, which defines the overall structure of the page, loads the CSS and JavaScript files, and imports other components, such as the header or navigation menu. The main content is rendered into a template file page.html, which extends the main layout and renders the body text.

The Sphinx awesome theme defines a number of internal extensions. The transformation of the reStructuredText sources to HTML is modified to produce less nested and more modern HTML, for example, using semantic HTML elements where feasible.

Some parts of the Sphinx/docutils toolchain are difficult to extend, and modifying a single line would result in copying and pasting the whole method. In such cases, the changes are implemented in a postprocessing extension that uses BeautifulSoup to parse the built HTML again.

Package and project management

The project is distributed as a Python package. The following tools are vital in order to achieve this:

The JavaScript and CSS portions of the theme are managed by Webpack. The entry point for Webpack is the file app.js. In this file, all dependencies are imported (including fonts and CSS styles).

Check the Webpack configuration file webpack.config.js for the full pipeline.