From 4ad6f60e3c0dde084e067d064e82a331f80c4198 Mon Sep 17 00:00:00 2001 From: Vladimir Izmalkov <48120135+izmalk@users.noreply.github.com> Date: Thu, 16 Apr 2026 21:22:06 +0100 Subject: [PATCH 01/10] Fix closing curly brackets --- docs/contribute/test-ulwazi-theme.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/contribute/test-ulwazi-theme.md b/docs/contribute/test-ulwazi-theme.md index b185a0ef..a1eaed0e 100644 --- a/docs/contribute/test-ulwazi-theme.md +++ b/docs/contribute/test-ulwazi-theme.md @@ -108,6 +108,7 @@ Add these new variables, including the top-level variables you declared earlier: "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: From a1d3ba9af8c22435074440b1ceb37f5a192a5381 Mon Sep 17 00:00:00 2001 From: Vladimir Izmalkov <48120135+izmalk@users.noreply.github.com> Date: Thu, 16 Apr 2026 22:11:23 +0100 Subject: [PATCH 02/10] Various wording updates and fixes --- docs/contribute/test-ulwazi-theme.md | 38 ++++++++++++++++++++++++---- 1 file changed, 33 insertions(+), 5 deletions(-) diff --git a/docs/contribute/test-ulwazi-theme.md b/docs/contribute/test-ulwazi-theme.md index a1eaed0e..0885d8bf 100644 --- a/docs/contribute/test-ulwazi-theme.md +++ b/docs/contribute/test-ulwazi-theme.md @@ -13,6 +13,9 @@ Ulwazi is a Sphinx theme built on Vanilla, with the base layout and functionalit 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 use RTD's preview branch feature to build a preview of the new look. + ## Update the dependencies In your project's Python requirements, replace the canonical-sphinx package with Ulwazi and its dependencies. The minimum set is: @@ -37,7 +40,19 @@ ulwazi ## Update the configuration -This is the most important and tricky part -- updating the project configuration. A reference `conf.py` with all the required configuration and TODO markers is provided in the Ulwazi repository as [`default-conf.py`](https://github.com/canonical/ulwazi/blob/main/docs/default-conf.py). Copy it as the starting point for a new documentation set, or use it as a checklist when migrating an existing one. +Updating the project configuration is the most critical step in this process. + +The Ulwazi repository provides a reference [`default-conf.py`](https://github.com/canonical/ulwazi/blob/main/docs/default-conf.py) with all required configuration options and TODO markers. + +You can prepare the configuration in one of two ways: + +* **Start from scratch** — copy [`default-conf.py`](https://github.com/canonical/ulwazi/blob/main/docs/default-conf.py) and fill in the values for your documentation. +* **Update your existing config** — edit your current `conf.py` to add all required values. + +We recommend starting from scratch with the default config, as it is the simpler path to getting initial results. +If your documentation uses many custom configuration parameters, updating the existing config may be more practical. + +The following instructions will guide you through all necessary modifications. ### Set the theme @@ -51,7 +66,7 @@ html_theme = "ulwazi" ### Update the extensions -In the list of extensions, replace canonical-sphinx with Ulwazi, and its dependencies: +In the list of extensions, replace `canonical-sphinx` with Ulwazi and its dependencies: ```{code-block} diff :caption: extensions in conf\.py @@ -66,7 +81,9 @@ In the list of extensions, replace canonical-sphinx with Ulwazi, and its depende If you need PDF output, add `sphinx_modern_pdf_style` to the list. -This is only a partial list. Your project may require additional extensions beyond those listed here. +```{caution} +Your project may require additional extensions beyond those listed here. +``` ### Add the required variables @@ -225,7 +242,10 @@ The license information is now conveyed through the "license" key in "html_conte ## Test the documentation -Once configuration is complete, review everything again and build it from scratch (cleaning out the existing build files first): +Once configuration is complete, do a final review. +Make sure all 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: ```shell cd docs @@ -233,6 +253,14 @@ make clean make run ``` -This will start a local server at http://127.0.0.1:8000. Open it in your browser to verify the pages render correctly. +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](https://github.com/canonical/ulwazi/issues/new). From 4dcd1a70cfb6edcbdde022092bf40d2a89fdc871 Mon Sep 17 00:00:00 2001 From: Vladimir Izmalkov <48120135+izmalk@users.noreply.github.com> Date: Thu, 16 Apr 2026 22:22:03 +0100 Subject: [PATCH 03/10] Fixes for the second gh issue --- docs/contribute/test-ulwazi-theme.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/contribute/test-ulwazi-theme.md b/docs/contribute/test-ulwazi-theme.md index 0885d8bf..61429b41 100644 --- a/docs/contribute/test-ulwazi-theme.md +++ b/docs/contribute/test-ulwazi-theme.md @@ -35,6 +35,7 @@ packaging sphinxcontrib-svg2pdfconverter[CairoSVG] sphinx-last-updated-by-git sphinx-sitemap +sphinx-terminal ulwazi ``` @@ -72,14 +73,14 @@ In the list of extensions, replace `canonical-sphinx` with Ulwazi and its depend :caption: extensions in conf\.py -"canonical-sphinx~=0.6" -+"ulwazi" ++"ulwazi", +"sphinx_terminal", +"canonical_sphinx_config", +"myst_parser", +"sphinxcontrib.jquery", ``` -If you need PDF output, add `sphinx_modern_pdf_style` to the list. +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. From 29478ef4d2c44c108d1b096f294c0e9655a2f86e Mon Sep 17 00:00:00 2001 From: Vladimir Izmalkov <48120135+izmalk@users.noreply.github.com> Date: Mon, 27 Apr 2026 19:56:57 +0100 Subject: [PATCH 04/10] Apply suggestions from review Co-authored-by: JJ Coldiron --- docs/contribute/test-ulwazi-theme.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/docs/contribute/test-ulwazi-theme.md b/docs/contribute/test-ulwazi-theme.md index 61429b41..4e3a2b02 100644 --- a/docs/contribute/test-ulwazi-theme.md +++ b/docs/contribute/test-ulwazi-theme.md @@ -14,7 +14,7 @@ Ulwazi is a Sphinx theme built on Vanilla, with the base layout and functionalit 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 use RTD's preview branch feature to build a preview of the new look. +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 @@ -43,7 +43,7 @@ ulwazi Updating the project configuration is the most critical step in this process. -The Ulwazi repository provides a reference [`default-conf.py`](https://github.com/canonical/ulwazi/blob/main/docs/default-conf.py) with all required configuration options and TODO markers. +The Ulwazi repository provides a [reference configuration file](https://github.com/canonical/ulwazi/blob/main/docs/default-conf.py) with the required options. You can prepare the configuration in one of two ways: @@ -72,7 +72,7 @@ In the list of extensions, replace `canonical-sphinx` with Ulwazi and its depend ```{code-block} diff :caption: extensions in conf\.py --"canonical-sphinx~=0.6" +-"canonical-sphinx~=0.6", +"ulwazi", +"sphinx_terminal", +"canonical_sphinx_config", @@ -243,8 +243,7 @@ The license information is now conveyed through the "license" key in "html_conte ## Test the documentation -Once configuration is complete, do a final review. -Make sure all required extensions are listed in both the `extensions` list in `conf.py` and the `requirements.txt` file. +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: From 6db7d13ac7b92a7294b1c1444dce4a9ec04af1da Mon Sep 17 00:00:00 2001 From: Vladimir Izmalkov <48120135+izmalk@users.noreply.github.com> Date: Mon, 27 Apr 2026 20:41:54 +0100 Subject: [PATCH 05/10] Update after review --- docs/contribute/test-ulwazi-theme.md | 28 +++++++++++++++++++--------- 1 file changed, 19 insertions(+), 9 deletions(-) diff --git a/docs/contribute/test-ulwazi-theme.md b/docs/contribute/test-ulwazi-theme.md index 4e3a2b02..a6fa55a6 100644 --- a/docs/contribute/test-ulwazi-theme.md +++ b/docs/contribute/test-ulwazi-theme.md @@ -18,7 +18,7 @@ You can build the Ulwazi-themed documentation locally from the branch or open a ## Update the dependencies -In your project's Python requirements, replace the canonical-sphinx package with Ulwazi and its dependencies. The minimum set is: +In your project's Python requirements, replace the Canonical Sphinx package with Ulwazi and its dependencies. The minimum set is: ```{code-block} text :caption: requirements.txt @@ -39,21 +39,31 @@ sphinx-terminal ulwazi ``` -## Update the configuration +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. -The Ulwazi repository provides a [reference configuration file](https://github.com/canonical/ulwazi/blob/main/docs/default-conf.py) with the required options. +There are two main ways to do that: + +* Simple way -- Start from the [Default Ulwazi configuration](https://github.com/canonical/ulwazi/blob/main/docs/default-conf.py) and update the values for your specific documentation. +* Hard way -- Start from the existing configuration and add 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. + +## The simple way -You can prepare the configuration in one of two ways: +Here is the simple way of trying Ulwazi: -* **Start from scratch** — copy [`default-conf.py`](https://github.com/canonical/ulwazi/blob/main/docs/default-conf.py) and fill in the values for your documentation. -* **Update your existing config** — edit your current `conf.py` to add all required values. +1. Copy the [Default Ulwazi configuration](https://github.com/canonical/ulwazi/blob/main/docs/default-conf.py) file inside your documentation folder. +2. Rename the old `conf.py` to some other name, like `old-conf.py`. +3. Rename the Default Ulwazi configuration file to `conf.py`. +4. Open them side by side and update variables in the default configuration file to have correct values for your documentation. -We recommend starting from scratch with the default config, as it is the simpler path to getting initial results. -If your documentation uses many custom configuration parameters, updating the existing config may be more practical. +## The hard way -The following instructions will guide you through all necessary modifications. +The following instructions will guide you through necessary modifications to support Ulwazi with your existing `conf.py` file. ### Set the theme From 981417ecabdd6761be60122d21bb1420516f2351 Mon Sep 17 00:00:00 2001 From: Vladimir Izmalkov <48120135+izmalk@users.noreply.github.com> Date: Mon, 27 Apr 2026 20:46:43 +0100 Subject: [PATCH 06/10] Update after review --- docs/contribute/test-ulwazi-theme.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/contribute/test-ulwazi-theme.md b/docs/contribute/test-ulwazi-theme.md index a6fa55a6..169137bc 100644 --- a/docs/contribute/test-ulwazi-theme.md +++ b/docs/contribute/test-ulwazi-theme.md @@ -77,7 +77,7 @@ html_theme = "ulwazi" ### Update the extensions -In the list of extensions, replace `canonical-sphinx` with Ulwazi and its dependencies: +In the list of extensions, replace Canonical Sphinx with Ulwazi and its dependencies: ```{code-block} diff :caption: extensions in conf\.py From 95aa2035a006d873044333eb4e6888af95c097cd Mon Sep 17 00:00:00 2001 From: Vladimir Izmalkov <48120135+izmalk@users.noreply.github.com> Date: Mon, 27 Apr 2026 22:22:38 +0100 Subject: [PATCH 07/10] Wording improvements after review --- docs/contribute/test-ulwazi-theme.md | 38 +++++++++++++++------------- 1 file changed, 20 insertions(+), 18 deletions(-) diff --git a/docs/contribute/test-ulwazi-theme.md b/docs/contribute/test-ulwazi-theme.md index 169137bc..4cebe261 100644 --- a/docs/contribute/test-ulwazi-theme.md +++ b/docs/contribute/test-ulwazi-theme.md @@ -18,25 +18,26 @@ You can build the Ulwazi-themed documentation locally from the branch or open a ## Update the dependencies -In your project's Python requirements, replace the Canonical Sphinx package with Ulwazi and its dependencies. The minimum set is: +In your project's Python requirements (`requirements.txt`), replace the Canonical Sphinx package with Ulwazi and its dependencies: -```{code-block} text +```{code-block} diff :caption: requirements.txt -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 +- 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. @@ -50,7 +51,7 @@ There are two main ways to do that: * Simple way -- Start from the [Default Ulwazi configuration](https://github.com/canonical/ulwazi/blob/main/docs/default-conf.py) and update the values for your specific documentation. * Hard way -- Start from the existing configuration and add 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. +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. ## The simple way @@ -63,7 +64,8 @@ Here is the simple way of trying Ulwazi: ## The hard way -The following instructions will guide you through necessary modifications to support Ulwazi with your existing `conf.py` file. +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. ### Set the theme From 07bfaaec28ded4bbed9eff85616492a0b6d0e0c5 Mon Sep 17 00:00:00 2001 From: Vladimir Izmalkov <48120135+izmalk@users.noreply.github.com> Date: Thu, 30 Apr 2026 17:19:44 +0100 Subject: [PATCH 08/10] Update the choice explanation --- docs/contribute/test-ulwazi-theme.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/contribute/test-ulwazi-theme.md b/docs/contribute/test-ulwazi-theme.md index 4cebe261..1e891a64 100644 --- a/docs/contribute/test-ulwazi-theme.md +++ b/docs/contribute/test-ulwazi-theme.md @@ -49,9 +49,11 @@ Updating the project configuration is the most critical step in this process. There are two main ways to do that: * Simple way -- Start from the [Default Ulwazi configuration](https://github.com/canonical/ulwazi/blob/main/docs/default-conf.py) and update the values for your specific documentation. -* Hard way -- Start from the existing configuration and add all required values. +* 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 default Ulwazi configuration. + ## The simple way From c5917866fd2a045ec5bc43338fdc56c6b20e1509 Mon Sep 17 00:00:00 2001 From: Vladimir Izmalkov <48120135+izmalk@users.noreply.github.com> Date: Thu, 30 Apr 2026 17:31:44 +0100 Subject: [PATCH 09/10] Update after review --- docs/contribute/test-ulwazi-theme.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/contribute/test-ulwazi-theme.md b/docs/contribute/test-ulwazi-theme.md index 1e891a64..10a21dda 100644 --- a/docs/contribute/test-ulwazi-theme.md +++ b/docs/contribute/test-ulwazi-theme.md @@ -48,12 +48,11 @@ Updating the project configuration is the most critical step in this process. There are two main ways to do that: -* Simple way -- Start from the [Default Ulwazi configuration](https://github.com/canonical/ulwazi/blob/main/docs/default-conf.py) and update the values for your specific documentation. +* Simple way -- Adapt the [Sample `conf.py` for Ulwazi](https://github.com/canonical/ulwazi/blob/main/docs/default-conf.py) 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 default Ulwazi configuration. - ## The simple way @@ -62,13 +61,15 @@ Here is the simple way of trying Ulwazi: 1. Copy the [Default Ulwazi configuration](https://github.com/canonical/ulwazi/blob/main/docs/default-conf.py) file inside your documentation folder. 2. Rename the old `conf.py` to some other name, like `old-conf.py`. 3. Rename the Default Ulwazi configuration file to `conf.py`. -4. Open them side by side and update variables in the default configuration file to have correct values for your documentation. +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](https://github.com/canonical/kafka-operator/pull/444/files#diff-85933aa74a2d66c3e4dcdf7a9ad8397f5a7971080d34ef1108296a7c6b69e7e3). + ### Set the theme Tell Sphinx to use Ulwazi as the theme: @@ -126,7 +127,6 @@ 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. -For an example of all the changes, see the [Charmed Apache Kafka Ulwazi PR](https://github.com/canonical/kafka-operator/pull/444/files#diff-85933aa74a2d66c3e4dcdf7a9ad8397f5a7971080d34ef1108296a7c6b69e7e3). The code snippets in this section might not match the exact layout of `html_context` in your `conf.py`. From aee5c73d0e9af5a22b32fb51fa0b183887c98277 Mon Sep 17 00:00:00 2001 From: Vladimir Izmalkov <48120135+izmalk@users.noreply.github.com> Date: Thu, 30 Apr 2026 17:41:44 +0100 Subject: [PATCH 10/10] Streamline sample/default terminology --- docs/contribute/test-ulwazi-theme.md | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/docs/contribute/test-ulwazi-theme.md b/docs/contribute/test-ulwazi-theme.md index 10a21dda..787cdec9 100644 --- a/docs/contribute/test-ulwazi-theme.md +++ b/docs/contribute/test-ulwazi-theme.md @@ -52,25 +52,25 @@ There are two main ways to do that: * 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 default Ulwazi configuration. +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 +### The simple way Here is the simple way of trying Ulwazi: -1. Copy the [Default Ulwazi configuration](https://github.com/canonical/ulwazi/blob/main/docs/default-conf.py) file inside your documentation folder. +1. Copy the [Sample `conf.py` for Ulwazi](https://github.com/canonical/ulwazi/blob/main/docs/default-conf.py) file inside your documentation folder. 2. Rename the old `conf.py` to some other name, like `old-conf.py`. -3. Rename the Default Ulwazi configuration file to `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 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](https://github.com/canonical/kafka-operator/pull/444/files#diff-85933aa74a2d66c3e4dcdf7a9ad8397f5a7971080d34ef1108296a7c6b69e7e3). -### Set the theme +#### Set the theme Tell Sphinx to use Ulwazi as the theme: @@ -80,7 +80,7 @@ Tell Sphinx to use Ulwazi as the theme: html_theme = "ulwazi" ``` -### Update the extensions +#### Update the extensions In the list of extensions, replace Canonical Sphinx with Ulwazi and its dependencies: @@ -101,7 +101,7 @@ If you need **PDF output**, add `sphinx_modern_pdf_style` to the extensions list Your project may require additional extensions beyond those listed here. ``` -### Add the required variables +#### Add the required variables Add and fill the following variables immediately before `html_context = {`: @@ -124,7 +124,7 @@ product_page = If your project is written in reST, set `default_source_extension` to `".rst"`. -### Update the HTML context +#### Update the HTML context You need to make several updates to the `html_context` dictionary. @@ -212,7 +212,7 @@ Add the following parameters for the footer. } ``` -### Add syntax highlighting +#### Add syntax highlighting Add these syntax highlighting settings after the list of extensions: @@ -223,7 +223,7 @@ highlight_language = "none" # default pygments_style = "autumn" # see https://pygments.org/styles for more ``` -### Configure the sitemap +#### Configure the sitemap Add the lastmod setting to the sitemap section: @@ -233,7 +233,7 @@ Add the lastmod setting to the sitemap section: sitemap_show_lastmod = True ``` -### Configure PDF output +#### Configure PDF output If you need to render your docs to PDF, add the following at the end of the configuration: @@ -243,7 +243,7 @@ If you need to render your docs to PDF, add the following at the end of the conf set_modern_pdf_config = True ``` -### Update the copyright +#### Update the copyright The Ulwazi theme expects a plain year string rather than the older {spellexception}`CC-BY-SA` format.