Metadata-Version: 2.4
Name: ulwazi
Version: 0.4
Summary: Ulwazi theme for Sphinx documentation projects
Author-email: "Canonical Ltd." <webteam@canonical.com>
License: GPL-3.0-only
Project-URL: Homepage, https://canonical-ulwazi.readthedocs-hosted.com/
Project-URL: Documentation, https://canonical-ulwazi.readthedocs-hosted.com/
Project-URL: Repository, https://github.com/canonical/ulwazi
Project-URL: Issues, https://github.com/canonical/ulwazi/issues
Keywords: sphinx,theme,documentation,vanilla,canonical
Classifier: Framework :: Sphinx
Classifier: Framework :: Sphinx :: Theme
Classifier: Development Status :: 4 - Beta
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Environment :: Console
Classifier: Environment :: Web Environment
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Documentation
Classifier: Topic :: Software Development :: Documentation
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: sphinx
Requires-Dist: sphinx-basic-ng
Requires-Dist: sphinxcontrib-jquery
Requires-Dist: beautifulsoup4
Provides-Extra: dev
Requires-Dist: requests; extra == "dev"
Dynamic: license-file

# Ulwazi Sphinx theme

Ulwazi, Xhosa for information, is a work-in-progress Sphinx theme based on [Vanilla design](https://github.com/canonical/vanilla-framework).

[Demo website](https://canonical-ulwazi.readthedocs-hosted.com/)

Layout and functionality is derived from [sphinx-basic-ng](https://github.com/pradyunsg/sphinx-basic-ng), developed by [praduimsg](https://github.com/pradyunsg) and [Alabaster](https://github.com/sphinx-doc/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](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) and [Yarn](https://yarnpkg.com/) installed:

```shell
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:

```shell
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:

```shell
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:

```shell
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.
