Sphinx Theme Builder requires the themes to follow a fairly specific project
layout and structure. This standard structure is what allows this tool to
provide a sensible build pipeline, which in-turn enables the nice
quality-of-life things like
How it looks#
Need for version control#
Sphinx Theme Builder does not enforce the use of Git but, as part of the build
process, it will exclude any files that are excluded from Git’s tracking using
any of the supported mechanisms (typically, a
.gitignore file in the
repository root). This information is queried as part of the source distribution
The following folders will be auto-generated when the theme’s assets are
compiled. Add them to the project’s
.nodeenv- The NodeJS (+
npm) installation that is used to compile the theme’s assets.
node_modules- The NodeJS packages that are installed for use, to compile the theme’s assets.
src/theme/<my-awesome-theme>/static/styles- The compiled CSS assets for the theme
src/theme/<my-awesome-theme>/static/scripts- The compiled JS assets for the theme
How to get this right#
Nearly everything about the filesystem layout and the contents of the various configuration files are validated, as part of the build process. This means that you can get the layout and contents of the files correct by ensuring that the build of the theme succeeds, when using Sphinx Theme Builder.
This typical workflow for doing this looks something like:
build-backendfor the theme to Sphinx Theme Builder.
[build-system] requires = ["sphinx-theme-builder >= 0.2.0a14"] build-backend = "sphinx_theme_builder"
stb packagein the same directory as the
Fix the error presented.
Repeat the above two steps, that until the
stb packagecommand succeeds.