ulwazi 0.3

Ulwazi theme for Sphinx documentation projects

Ulwazi Sphinx theme

Ulwazi, Xhosa for information, is a work-in-progress Sphinx theme based on Vanilla design.

Demo website

Layout and functionality is derived from sphinx-basic-ng, developed by praduimsg and Alabaster.

The theme will default to a generic Vanilla Framework style but will have options for the specific Canonical theming to support the org's documentation needs.

Installing Node Modules

Make sure you have npm and Yarn installed:

sudo apt install npm
sudo npm install -g corepack

If you do not have the node_modules directory (for example, after cloning the repository for the first time), install the JavaScript dependencies:

yarn install

Testing

A Makefile includes some basic functionality to build the theme and then build and run the test content with the theme.

To build the sample documentation using the theme, run:

make run

This command set ups a virtual environment, installs dependencies, builds theme, then documentation in this repo, and serves the result via local web server.

The resulted environment tracks changes in sample content and rebuilds the local website automatically. However, changes to the theme might require a full rebuild of the theme package:

make rebuild

This command runs make clean to delete files built earlier, and then make run again.

If you change dependencies (for example, add a new Sphinx extension to the docs/requirements.txt file), you will need to re-build the virtual environment entirely. That can be done by manually deleting the .venv folder or with the make fclean command.

Contributing

The theme files are located in the ulwazi folder:

• __init__.py -- initialization script for the theme.
• navigation.py -- modifies the global TOC navigation tree
• theme/ulwazi/ -- contains the theme files
  • theme.toml -- theme configuration file
  • static -- static content to be used by the theme without processing
  • other files -- HTML templates for Sphinx using Jinja templating engine

If you want to modify HTML code of a page generated by Sphinx before the theme gets applied, see the _html_page_context function definition in the initialization script.