Architecture of the repository#
This is a short overview of the general architecture and structure of the repository, to help you orient yourself.
This theme uses sphinx-theme-builder as its build backend, and follows the filesystem layout recommended by it. See below for some more specific sections
Architecture of the repository
package.json- Webpack and dependencies
src/sphinx_book_theme/ - Theme source files#
This folder contains all of the source files for this theme, and most changes to the theme are made somewhere inside this folder.
The theme’s Python module, which runs several configuration and set-up steps. This module does things like load in Sphinx’s default HTML for the sidebar, and modify it in order to have dropdown nested lists. It also inserts several variables into the Jinja template context that are then used in our HTML templates.
Scripts to generate metadata for buttons in the header. We use Jinja Macros (in the
macros/folder) to generate the HTML for header buttons. The scripts in
header_buttons/generate the data structure that is used to generate buttons with these macros (in the
Logic to create the correct URLs for our launch buttons. This basically means building the URL for a given launch service in a proper fashion.
The other folders in this section are described in the next few sections.
/theme/sphinx_book_theme/ - HTML templates#
This is the actual theme source that is packaged and distributed via PyPI. It contains HTML templates that make up the theme structure.
These follow the
sphinx-basic-ng template structure.
layout.htmlinherits from the pydata sphinx theme and modifies several sections.
theme.confcontains the Sphinx configuration file for this theme.
macros/contains HTML templates that define Jinja macros
sections/contains HTML templates for major sections of the page.
components/contains HTML templates for smaller, self-contained parts of the page.
stb compile). They are not checked in to
/assets/styles - SCSS assets#
Contains SCSS files for this theme. These are compiled and bundled with the theme at build time. See the Style and Design section for more information.
/translations/ - Translations and internationalization#
This folder contains all of the translations that we use in this theme, so that it may be used in many different base languages.
For more information about our translation infrastructure, see
docs/ - Site documentation#
The documentation for the theme, written as a Sphinx documentation site. The documentation tries to follow the Diataxis.fr documentation framework.
Here is a brief overview:
docs/*.md: Contains several topic sections for the documentation (e.g.
content-blocks.mdcovers special content blocks for this theme)
docs/tutorials/: Step-by-step tutorials that cover how to do a particular thing from beginning to end.
docs/reference/: Reference sections of the documentation, to demonstrate the look and feel of the theme. The “kitchen sink” is pulled directly from the
sphinx-themeswebsite. There are also other sections for theme-specific elements.
package.json - Webpack and dependencies#
webpack.config.js contains the compilation code to convert source files like SCSS and JS in
src/sphinx_book_theme/assets/* into the production assets in
This compilation is called by default, during development commands (see below).
tests/ - Testing infrastructure#
Testing infrastructure that uses
pytest along with
beautifulsoup to validate
that the generated HTML is what we expect it to be.
Much of these tests also use
pytest-regressions, to check whether newly-generated HTML differs from previously-generated HTML.
.github/workflows/ - Continuous Integration and Deployment#
Contains Continuous-integration (CI) workflows, run on commits/PRs to the GitHub repository.
Parent theme -
This theme inherits a lot of functionality and design rules from its parent theme, the PyData Sphinx Theme. This is a theme designed for the PyData community, with a similar look and feel to the book theme. Over time, we try to upstream any improvements made here into the parent theme, as long as the look and feel is the same between the two.
If you come across something in the codebase and you’re not sure where it comes from (an example is the
generate_nav_html function), you should check the PyData Theme source files to see if it is defined there.