Thanks for your interest in contributing to this project!
The most valuable contribution to this project would be to contribute more awesome Sphinx themes!
Every theme must be available as a PyPI package, and only 1 entry is permitted for a package.
Themes are stored in themes.json
. To add a theme to the website, an entry should be added to this JSON document.
The entries in this JSON document are sorted by tools/sort-json.py
. Notably, third-party themes are ordered alphabetically based on the PyPI package name after sphinx-rtd-theme
. Make sure that the JSON entry is in the correct location and linted as tools/sort-json.py
would output it (sorted keys, each entry in arrays/objects starts on a newline). Otherwise, the CI will show a lot of red text and icons and we won't be able to merge the PR.
For themes which only need html_theme
to be set, the entry would be something like:
{
"config": "sphinx_rtd_theme",
"display": "Read the Docs Sphinx Theme",
"pypi": "sphinx-rtd-theme"
}
config
becomes thehtml_theme
in Sphinx'sconf.py
display
is the name presented on the websitepypi
is the package installed for the theme from PyPI
In cases where additional values must be set in conf.py
, you can use a JSON object for "config" as follows:
{
"config": {
"html_theme": "my_awesome_theme",
"_imports": ["sys"],
"_extensions": ["sphinx_tabs"],
"my_theme_colors": "['blue', 'indigo']",
"my_theme_number": "1",
"html_context": "{'executable': sys.executable}"
},
"display": "Read the Docs Sphinx Theme",
"pypi": "sphinx-rtd-theme"
}
This will result in a conf.py containing:
import sys
extensions.append("sphinx_tabs")
html_theme = "my_awesome_theme"
my_theme_colors = ['blue', 'indigo']
my_theme_number = 1
html_context = {'executable': sys.executable}
Notice that:
_imports
was transformed into import statements._extensions
was transformed intoextensions.append(...)
statements."html_theme"
was automatically quoted.- All other properties were added as-is without any processing.
If you want to build this website locally, you need:
- Python 3.8 or newer
chromedriver
and Google Chromenox
installed in a virtualenv or withpipx
$ nox -s publish
Generates the entire site in public/
. The generated site is meant to be viewed using an HTTP server. You can use Python's http.server
module to create such a server locally using python -m http.server -d public
. This should make it possible to view the generated website at localhost:8000.
$ nox -s publish -- sphinx-rtd-theme
Generates the site in public/
, while only generating assets (sample-site and preview-image) for the given theme name(s). Multiple theme names can be passed after the --
. This is useful when adding one or more new themes, to ensure that the configuration is correct.
If you use this command, make sure to not include sample-docs/conf.py changes in any commits you make.
$ nox -s lint
Runs the linters and formats all the files in the repository. This uses pre-commit
for running the linters. Notably, tools/sort-json.py
is also run as part of these linters and formats themes.json
.
nox -s publish
generates the various parts of the website as follows:
-
nox -s render-sample-sites
: Generate the sample site.- For every theme:
- Create an isolated virtualenv in
.venv
and install sphinx + theme's PyPI package. - Patch
sample-docs/conf.py
according to what's needed for the theme. - Call
sphinx-build
to render the documentation using given theme.
- Create an isolated virtualenv in
- For every theme:
-
nox -s generate-previews
: Generate the preview images.- Install the required packages.
- Run
tools/generate-previews.py
- Creates a selenium driver for Google Chrome.
- For every theme:
- Open the generated sample site's root.
- Take screenshots for various resolutions.
- Place the screenshots appropriately in
src/template.png
- Write the appropriately-modified-for-web-use preview image.
-
nox -s render-index
: Rendering the index page.- Renders
src/index.jinja2
using Jinja2 and themes loaded fromthemes.json
.
- Renders
This is done using GitHub Actions.
The GitHub Action job runs the various nox -s ...
commands and pushes the generated site to the gh-pages
branch of this repository. GitHub Pages hosts the website which is served through https://sphinx-themes.org.