Contribute to Plone Sphinx Theme

Contribute to Plone Sphinx Theme#

This document describes how to install Plone Sphinx Theme for contributing code to this project, and what you can modify. It also covers the essential commands for building and previewing

Prerequisites#

uv#

Install uv using the standalone installer method.

Install Plone Sphinx Theme#

Begin by cloning the Plone Sphinx Theme repository from GitHub.

git clone https://github.com/plone/plone-sphinx-theme.git

Change your working directory to the cloned repository.

cd plone-sphinx-theme

Then install a supported Python version for development, create a Python virtual environment, install requirements for development, and install the package in development mode with a single command.

make dev

Change log entry#

Plone Sphinx Theme requires that you include a change log entry or news item with your contribution. Your attribution must be in the format of @github_username.

See also

For details see Change log entry.

Edit documentation#

You can edit documentation located in the directory docs, except for the files contained in docs/reference/kitchen-sink.

Danger

Do not directly edit files in the directory docs/reference/kitchen-sink. These files are copied from the source of the demonstration website Sphinx Themes Gallery whenever there is an update to it. See Update Kitchen Sink demonstration for details.

Update Kitchen Sink demonstration#

From time to time, the demonstration files for Sphinx Themes Gallery need to be updated. Plone Sphinx Theme uses these files as a demonstration for its styles. To copy these updated files to Plone Sphinx Theme, run the following command.

make kitchen-sink-update

Override build configuration options#

Both Sphinx and Vale support overriding configuration options. The following examples serve as tips for spotting mistakes in your documentation when you have too many errors or warnings.

In Sphinx, you can use the SPHINXOPTS environment variable to set configuration options of sphinx-build. Syntax is in the following form.

make SPHINXOPTS="OPTION VALUE" BUILDER

The following example shows how to clean then build a live HTML preview of the documentation while suppressing syntax highlighting failures.

make SPHINXOPTS="-D suppress_warnings='misc.highlighting_failure'" clean livehtml

You can also pass options to Vale in the VALEOPTS environment variable. In the following example, Vale will not return a non-zero exit code when there are errors and will display warnings or errors only, not suggestions.

make vale VALEOPTS="--no-exit --minAlertLevel='warning'"

Edit the theme#

You can edit the Plone Sphinx Theme's layout, content, styles, and JavaScripts. This section describes how you can change this theme.

See also

File system structure

Add or edit a template#

Templates are pages of Jinja2 code into which components can be inserted. Plone Sphinx Theme uses a template, 404.html to display an HTTP "404 Not Found" response page to visitors when they request a page that doesn't exist. In Plone Sphinx Theme, templates are located in the directory src/plone_sphinx_theme/theme/plone-sphinx-theme.

Add or edit a component#

Components are snippets of Jinja2 code that can be inserted in templates. In Plone Sphinx Theme, components are located in the directory src/plone_sphinx_theme/theme/plone-sphinx-theme/components.

Add or edit styles#

Plone Sphinx Theme uses Sass and webpack to compile a CSS file for its theme. You can edit these files located in the directory src/plone_sphinx_theme/assets/styles, except for those in src/plone_sphinx_theme/assets/styles/sphinx-book-theme.

Danger

Do not directly edit files in the directory src/plone_sphinx_theme/assets/styles/sphinx-book-theme. These files are copied from the parent theme whenever there is an update to it. See Update parent theme styles for details.

Build and reload#

Compile static assets, build and serve the docs, and reload the browser on changes.

make serve

Compile static assets#

After editing any of the static assets, you need to compile them. This step is included in the make serve command.

make compile

Update parent theme styles#

From time to time, the parent theme, Sphinx Book Theme, will update its Sass files. Plone Sphinx Theme uses these files as a base for its styles. To copy these updated files to Plone Sphinx Theme, run the following command.

make sbt-styles-update

Add or edit JavaScripts#

Plone Sphinx Theme uses webpack to compile a JavaScript file for its theme. You can edit these files located in the directory src/plone_sphinx_theme/assets/scripts.

Update requirements#

Requirements are managed with uv in the uv.lock. They are declared in the pyproject.toml.

Update requirements in your development environment.

uv sync

Add a development requirement.

uv add --dev my-requirement

Release#

To release Plone Sphinx Theme, use the following command.

make release

This command runs zest.releaser to make a full release.

Contents