The LUE documentation is generated using Sphinx. The configuration is stored in document/doc/conf.py.in.
The theme we use is an updated version of the Read the Docs Sphinx Theme. We forked that project and based our theme on release 0.5.0. When LUE is configured and the documentation target is requested, the CMake script will checkout our fork containing the LUE Sphinx Theme in the build directory. The Sphinx configuration file will pick up the theme.
If you want to update the LUE Sphinx Theme, then this is more or less the procedure:
# Initialize a Conda environment specifically for changing the theme cd lue conda env create -f environment/configuration/conda_rtd_environment.yml conda activate lue_rtd # Checkout the theme's sources from its branch cd .. git clone firstname.lastname@example.org:computationalgeography/sphinx_rtd_theme.git cd sphinx_rtd_theme git checkout lue_theme # Install software required for testing and generating the theme # See https://sphinx-rtd-theme.readthedocs.io/en/latest/contributing.html pip install -e '.[dev]' npm install # Start an HTTP server that will pick-up changes to SASS files npm run dev # Change the theme's SASS files # ... # Generate the theme's CSS npm run build # Check in changes to SASS files and CSS files # ...
The colours used in the theme are taken from the Nord theme. The goal of the theme is to use less colours and hover effects than the original one.
The LUE-specific overrides of the underlying theme are located
src/sass/_lue_theme_*.sass. These SASS files are included from
When committing, skip
package-lock.json. It doesn’t seem to be necessary
Don’t forget to generate and commit the theme’s CSS
sphinx_rtd_theme/static/css/theme.css). Otherwise, the changes
to the theme will not be visible to users.
Updating LUE to pick up the updated Sphinx theme involves these steps:
Note the commit hash in the updated
Update commit hash in
If you use a local repository cache, pull in updates in the
Remove current theme sources from build directory:
cd $LUE_OBJECTS rm -r _deps/sphinx_lue_theme-*
cd $LUE_OBJECTS rm -r document/doc/sphinx/ make sphinx_doc