owcustom sphinx theme

A Sphinx theme for OpenWISP docs, based on Read The Docs default theme (sphinx_rtd_theme).

Live demo: https://owcustom-sphinx-theme.readthedocs.io/en/latest/

Installation

This theme is distributed on PyPI as owcustom-sphinx-theme and can be installed with pip:

$ python3 -m pip install owcustom-sphinx-theme

To use the theme in your Sphinx project, you will need to add the following to your conf.py file:

# add this extension
extensions = [...,
'owcustom.sphinx.theme',
...
]
html_theme = "owcustom-sphinx-theme"

Development

python3 -m pip install -e .
make clean # not always needed, but better to be cautious
make html
open build/html/index.html

Releasing

1. Make sure all your changes have been commited to the main branch.

2. Add a commit which describes the changes from the previous version to CHANGES.rst and updates the version number in lib/owcustom/sphinx/theme/VERSION.

3. Tag this commit with the version number, e.g. git tag -a 1.0.x -m "version 1.0.x".

4. Push the commit and tag to GitHub, e.g. git push origin main 1.0.x.

5. Publish to PyPI by invoking a GitHub Actions workflow:

   1. Go to the workflow: publish.yml.

   2. Select Run workflow. In the new menu:

      1. Select Use workflow from > Tags > new version number (e.g. 2022.12).

      2. Set PyPI instance for publishing as PyPI (default) or TestPyPI. More info

      3. Select Run workflow.