Contribution guide

Thank you for your interest in contributing to the Ulwazi Sphinx theme! This guide will help you get started with building, testing, and developing the theme.

Prerequisites

Install npm and Yarn:

sudo apt install npm
sudo npm install -g corepack

Setup

  1. Install Node.js dependencies (if you don’t have a node_modules directory):

    yarn install

  2. Build the sample documentation with the theme:

    make docs

    This sets up a virtual environment, installs dependencies, and builds the sample docs.

You can rebuild the theme manually, which is especially useful if you make significant theme changes outside of the docs content:

make rebuild

This does a clean build, which may be necessary after changes to the theme files.

Reset the environment

Some changes to the environment (for example, if you add a new package to pyproject.toml) may require a complete reset by deleting the virtual environment. To reset the virtual environment:

  1. Delete the .venv folder manually or run:

    make clean

  2. Build the documentation from scratch with build docs.

Rebuild CSS

To rebuild the theme/ulwazi/static/css/vanilla-main.css css file after making any changes to the SCSS files it consists of:

make vanilla-main

Theme files layout

The following list contatins some of the most important files and folders to focus on for contributing to this theme:

  • ulwazi/__init__.py – Theme initialization and core hooks

  • ulwazi/navigation.py – Manages the global TOC navigation tree

  • ulwazi/theme/ulwazi/ – Contains all theme files:

    • theme.toml – Theme configuration

    • static/ – Static assets (CSS, JS, images)

    • HTML files – Jinja templates used by Sphinx (look for .html files)

Other files of interest for development:

  • ulwazi/product_menu_gen.py – Product menu generation logic

  • ulwazi/tests/ – Automated tests for the theme

HTML customization

To modify the HTML of pages generated by Sphinx (before the theme is applied), see the _html_page_context function in ulwazi/__init__.py.

Further resources

All contributions are welcome: bug reports, feature requests, and pull requests.