Ulwazi, Xhosa for information, is a work-in-progress Sphinx theme based on Vanilla design.
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.
Make sure you have npm and Yarn installed:
sudo apt install npm
sudo npm install -g corepackIf you do not have the node_modules directory (for example, after cloning the repository for the first time), install the JavaScript dependencies:
yarn installA 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 runThis 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 rebuildThis 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.
The theme files are located in the ulwazi folder:
__init__.py-- initialization script for the theme.navigation.py-- modifies the global TOC navigation treetheme/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.