Test the Ulwazi theme

Ulwazi is a Sphinx theme built on Vanilla, with the base layout and functionality derived from sphinx-basic-ng.

This guide outlines the steps required to use the Ulwazi theme in your Sphinx documentation project.

We recommend creating a new branch of your repository and testing Ulwazi in that branch. You can build the Ulwazi-themed documentation locally from the branch or open a PR and view the changes in its RTD preview.

Update the dependencies

In your project’s Python requirements (requirements.txt), replace the Canonical Sphinx package with Ulwazi and its dependencies:

requirements.txt
- canonical-sphinx
+ sphinx
+ build
+ sphinx-autobuild
+ canonical-sphinx-config @ git+https://github.com/Canonical/canonical-sphinx-config.git@main
+ myst-parser~=4.0
+ sphinx-basic-ng
+ sphinxcontrib-jquery
+ beautifulsoup4
+ packaging
+ sphinxcontrib-svg2pdfconverter[CairoSVG]
+ sphinx-last-updated-by-git
+ sphinx-sitemap
+ sphinx-terminal
+ ulwazi

Be ready to add any other missing extensions if you see errors about them.

Main configuration

Updating the project configuration is the most critical step in this process.

There are two main ways to do that:

  • Simple way – Adapt the Sample conf.py for Ulwazi by adjusting the values for your specific documentation.

  • Hard way – Adapt your existing configuration by adding all required values.

We strongly recommend trying the first option (the simple way) first as it proved to be faster and less troublesome, yet enough for testing the theme. Choose the hard way if your project already has significant conf.py customisation that would be difficult to recreate from the Sample conf.py for Ulwazi.

The simple way

Here is the simple way of trying Ulwazi:

  1. Copy the Sample conf.py for Ulwazi file inside your documentation folder.

  2. Rename the old conf.py to some other name, like old-conf.py.

  3. Rename the sample configuration file to conf.py.

  4. Open the old and new files side by side and update relevant values in the new configuration file for your specific product and documentation.

The hard way

The following instructions describe the modifications needed to support Ulwazi in an existing conf.py file. Use this approach if you want to preserve as much of your original conf.py as possible, for example in a heavily customised deployment or when troubleshooting a configuration issue.

For an example of all the changes, see the Charmed Apache Kafka Ulwazi PR.

Set the theme

Tell Sphinx to use Ulwazi as the theme:

conf.py
html_theme = "ulwazi"

Update the extensions

In the list of extensions, replace Canonical Sphinx with Ulwazi and its dependencies:

extensions in conf.py
-"canonical-sphinx~=0.6",
+"ulwazi",
+"sphinx_terminal",
+"canonical_sphinx_config",
+"myst_parser",
+"sphinxcontrib.jquery",

If you need PDF output, add sphinx_modern_pdf_style to the extensions list and sphinx-modern-pdf-style to requirements.txt.

Caution

Your project may require additional extensions beyond those listed here.

Add the required variables

Add and fill the following variables immediately before html_context = {:

# TODO: Adjust to point to the repository where your documentation source files
# are stored.
github_repo = <https://github.com/your-org/your-repo>

# TODO: Select the default syntax for docs source files.
# This is for a fallback view/edit source code buttons.
default_source_extension = ".md"

# TODO: Change to your product website URL,
#       dropping the 'https://' prefix, e.g. 'ubuntu.com/lxd'.
product_page = <link-to-product-website>

If your project is written in reST, set default_source_extension to ".rst".

Update the HTML context

You need to make several updates to the html_context dictionary.

The code snippets in this section might not match the exact layout of html_context in your conf.py file.

Add these new variables, including the top-level variables you declared earlier:

html_context in conf.py
"product_page": product_page,      # was: "your-product.example.com"
"github_url": github_repo,         # was: "https://github.com/your-org/your-repo"
"license": {
    "name": "Apache-2.0",          # TODO: set your license
    "url": github_repo + "/blob/main/LICENSE",
},

Add these entries so the theme can display the project name and author without duplicating them:

html_context in conf.py
"project": project,
"author": author,

Add these entries to configure the settings related to your GitHub repository. default_edit_url and default_view_url serve as fallback URLs for the view/edit source buttons on pages that do not have a specific source file path set.

html_context in conf.py
"feedback": True,
"github_issues": "enabled",
"default_source_extension": default_source_extension,
"default_edit_url": github_repo + "/edit/main/docs/index" + default_source_extension,
"default_view_url": github_repo + "/blob/main/docs/index" + default_source_extension,

Add the horizontal navigation menu configuration:

html_context in conf.py
# Horizontal Nav Menu
"company": "Canonical",
# "link1_URL": "https://example.com/",
# "link1_name": "First optional link",
# "link2_URL": "https://example.com/",
# "link2_name": "Second optional link",

Uncomment and adjust the parameters for link1 and link2 if you want to add the links in the top navigation bar.

Add main logo parameters and adjust their values for your documentation:

html_context in conf.py
# Canonical Product menu
# Uncomment if you need a product menu added on the top of every page
# "add_product_menu": True,

"logo_link_URL": "https://documentation.ubuntu.com",
"logo_img_URL": "https://assets.ubuntu.com/v1/82818827-CoF_white.svg",
"logo_title": "Canonical",

Add the following parameters for the footer.

html_context in conf.py
# TODO: Customize the footer.
"footer": {
    # Whether to add the product name as the first entry.
    "product": True,
    # Whether to add the license as the second entry.
    "license": True,
    # List your footer entries. Accepts HTML tags.
    "entries": [
        '<a class="js-revoke-cookie-manager" href="#tracker-settings">Manage your tracker settings</a>',
    ]
}

Add syntax highlighting

Add these syntax highlighting settings after the list of extensions:

conf.py
highlight_language = "none"  # default
pygments_style = "autumn"    # see https://pygments.org/styles for more

Configure the sitemap

Add the lastmod setting to the sitemap section:

conf.py
sitemap_show_lastmod = True

Configure PDF output

If you need to render your docs to PDF, add the following at the end of the configuration:

conf.py
set_modern_pdf_config = True

Test the documentation

Once configuration is complete, make sure the required extensions are listed in both the extensions list in conf.py and the requirements.txt file.

Build the documentation from scratch by first cleaning out any existing build files:

cd docs
make clean
make run

If the build fails, check the build logs to identify the cause. Common issues are:

  1. Missing extensions

  2. Missing required values in conf.py

Fix any issues and rebuild.

Once the build succeeds, a local server starts at http://127.0.0.1:8000. Open that URL in your browser to verify that the pages render correctly.

Report issues or feature requests in the Ulwazi GitHub repository.