Veldus Sphinx Theme

This is a fork of the official Read the Docs theme for Sphinx. See their theme documentation for more information.

Installation

This theme is distributed on PyPI and can be installed with pip:

$ pip install sphinx_veldus_theme

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

import sphinx_veldus_theme

extensions = [
    ...
    "sphinx_veldus_theme",
]

html_theme = "sphinx_veldus_theme"

For more information read the full documentation on installing the theme

Configuration

This theme is highly customizable on both the page level and on a global level. To see all the possible configuration options, read the documentation on configuring the theme.

Modifying the theme

The styles for this theme use SASS and a custom CSS framework called Wyrm. We use Webpack and node-sass to build the CSS. Webpack is used to watch for changes, rebuild the static assets, and rebuild the Sphinx demo documentation.

Note

The installation of Node is outside the scope of this documentation. You will need Node version 10+ in order to make changes to this theme.

Set up your environment

1. Install Sphinx and documentation build dependencies.

   $ pip install -e '.[dev]'

2. Install Webpack, node-sass, and theme dependencies locally.

   $ npm install

Making changes

Changes to the theme can be compiled and tested with Webpack:

$ npm run dev

This script will do the following:

1. Install and update any dependencies.
2. Build the static CSS from SASS source files.
3. Build the demo documentation.
4. Watch for changes to the SASS files and documentation and rebuild everything on any detected changes.

Updating PyPI

After making an update to the project, you need to build, package, then update PyPI with the new updates.

Build

Run the release build script:

$ npm run build

Package the build

Find more information about packaging at the Python Packaging User Guide.

$ python3 setup.py sdist bdist_wheel

Uploading

Use Twine to upload the new package to PyPi:

$ python3 -m twine upload dist/*

Note

This will attempt to upload everything in your dist/ directory. Either remove unwanted files, and change dist/* to be more specific.