Improve Test the Ulwazi theme guide by izmalk · Pull Request #588 · canonical/sphinx-stack

izmalk · 2026-04-16T21:29:33Z

This PR clarifies and fixes the guide for testing the Ulwazi theme, addressing some of the issues reported in #580 and #581.

Fixes:

Added missing sphinx-terminal to the requirements.txt.
Fixed missing comma after "ulwazi" in the extensions diff block, which would cause a Python syntax error.
Noted that sphinx-modern-pdf-style must also be added to requirements.txt when enabling PDF output.
Fixed a missing closing }, in the html_context "license" block.

Improvements:

Added an introductory recommendation to work in a separate branch and use RTD's preview feature.
Revamped the starting section with clearer message of two alternative paths, with one being recommended as the simple way of testing Ulwazi.
Expanded the "Test the documentation" section to include a pre-build checklist and troubleshooting guidance for common build failures.
Various small wording and clarity improvements throughout.

Have you updated CHANGELOG.md with relevant non-documentation file changes?
Have you updated the documentation for this change?

jahn-junior

Thanks! I left some optional suggestions on wording.

Co-authored-by: JJ Coldiron <jj.coldiron@canonical.com>

jahn-junior

Thanks! I left one additional comment, but you've addressed the rest of my suggestions.

rkratky · 2026-04-30T17:18:38Z

 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
+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).


Nitpick: The PR includes many other changes (formatting, etc.) that need to be ignored to see the Ulwazi-specific ones.

If providing an example diff/PR like this, it should be against the vanilla SP and free of anything else than the Ulwazi changes.

I realize that's likely out of scope of this PR, so I'd rather leave this out.

minaelee · 2026-04-30T17:04:31Z

+
+Updating the project configuration is the most critical step in this process.
+
+There are two main ways to do that:


Suggested change

There are two main ways to do that:

There are two main ways:

minaelee · 2026-04-30T17:06:47Z

 ## 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:


It's unclear to me what's meant here by "Ulwazi's dependencies". A lot of these extensions already exist in the default starter pack extensions.txt.

That's a great point, that leads me to an idea of separating minimum dependencies from the ones we use in our Ulwazi demo. I'll add it as a feature request to our GitHub issues.

minaelee · 2026-04-30T17:07:57Z


-### Set the theme
+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.


Suggested change

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.

Use this approach if you want to preserve as much of your original `conf.py` as possible, for example in a heavily customized deployment or when troubleshooting a configuration issue.

minaelee · 2026-04-30T17:08:44Z

+* 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.


Suggested change

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 simple way first as it proved to be faster and less troublesome, yet enough for testing the theme.

minaelee · 2026-04-30T17:42:50Z

 copyright = f"{datetime.date.today().year}"
 ```

 The license information is now conveyed through the "license" key in "html_context".


Suggested change

The license information is now conveyed through the `license` key in `html_context`.

minaelee · 2026-04-30T17:51:11Z

+ sphinx-last-updated-by-git
+ sphinx-sitemap
+ sphinx-terminal
+ ulwazi


I would add sphinx-modern-pdf-style here as well. If someone follows the simpler approach described below, then sphinx_modern_pdf_style is included in the extensions list in default_conf.py, and the instruction to add sphinx-modern-pdf-style to requirements.txt only appears in the instructions for the harder approach. Might as well include it in the default requirements.txt even if not every docs set needs it (not every docs set needs myst-parser either but it's included).

minaelee · 2026-04-30T17:55:32Z

 ```

 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.


Suggested change

The `default_edit_url` and `default_view_url` settings serve as fallback URLs for the view/edit source buttons on pages that do not have a specific source file path set.

Optional nit; I prefer to avoid starting a sentence with a lower-case letter if possible.

minaelee · 2026-04-30T17:57:44Z

 "feedback": True,
 "github_issues": "enabled",
 "default_source_extension": default_source_extension,
 "default_edit_url": github_repo + "/edit/main/docs/index" + default_source_extension,


Just a note, not for this PR necessarily but for eventual implementation into the starter pack, it would be better not to use main here (or anywhere else) and have a variable set somewhere that reflects the branch to use, defaulting to main. Some repos use multiple branches for various versions.

minaelee · 2026-04-30T17:57:56Z

-### Configure the sitemap
+#### Configure the sitemap

 Add the lastmod setting to the sitemap section:


Suggested change

Add the lastmod setting to the sitemap section: Add the `lastmod` setting to the sitemap section:

Note this has been in the starter pack for a while; maybe add "if it doesn't already exist."

minaelee · 2026-04-30T18:07:45Z

 ## 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, make sure the required extensions are listed in both the `extensions` list in `conf.py` and the `requirements.txt` file.


Might be worth mentioning that extensions bundled with Sphinx (that start with sphinx.ext., such as sphinx.ext.intersphinx) are exceptions; they only need to be listed in conf.py.

izmalk added 3 commits April 16, 2026 21:22

Fix closing curly brackets

4ad6f60

Various wording updates and fixes

a1d3ba9

Fixes for the second gh issue

4dcd1a7

izmalk self-assigned this Apr 16, 2026

izmalk requested review from SecondSkoll, akcano, dwilding, medubelko, minaelee, rkratky and tang-mm as code owners April 16, 2026 21:29

izmalk mentioned this pull request Apr 16, 2026

Tested docs: several build failures canonical/ulwazi#90

Open

a-velasco added the documentation Improvements or additions to documentation label Apr 21, 2026

jahn-junior reviewed Apr 27, 2026

View reviewed changes

izmalk and others added 3 commits April 27, 2026 19:56

Apply suggestions from review

29478ef

Co-authored-by: JJ Coldiron <jj.coldiron@canonical.com>

Update after review

6db7d13

Update after review

981417e

izmalk requested a review from jahn-junior April 27, 2026 19:46

jahn-junior reviewed Apr 27, 2026

View reviewed changes

Comment thread docs/contribute/test-ulwazi-theme.md Outdated

izmalk added 2 commits April 27, 2026 22:22

Wording improvements after review

95aa203

Merge branch 'main' into ulwazi-guide-update

1a5b422

izmalk requested a review from jahn-junior April 27, 2026 21:28

jahn-junior approved these changes Apr 27, 2026

View reviewed changes

Comment thread docs/contribute/test-ulwazi-theme.md

rkratky reviewed Apr 30, 2026

View reviewed changes

Comment thread docs/contribute/test-ulwazi-theme.md Outdated

izmalk added 3 commits April 30, 2026 17:19

Update the choice explanation

07bfaae

Update after review

c591786

Merge branch 'main' into ulwazi-guide-update

072f94d

izmalk requested a review from rkratky April 30, 2026 16:35

Streamline sample/default terminology

aee5c73

rkratky reviewed Apr 30, 2026

View reviewed changes

rkratky approved these changes Apr 30, 2026

View reviewed changes

jahn-junior merged commit ab97909 into canonical:main Apr 30, 2026
8 of 11 checks passed

minaelee reviewed Apr 30, 2026

View reviewed changes


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

		There are two main ways to do that:

	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.
	Use this approach if you want to preserve as much of your original `conf.py` as possible, for example in a heavily customized deployment or when troubleshooting a configuration issue.

	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 simple way first as it proved to be faster and less troublesome, yet enough for testing the theme.


	The license information is now conveyed through the `license` key in `html_context`.


	The `default_edit_url` and `default_view_url` settings serve as fallback URLs for the view/edit source buttons on pages that do not have a specific source file path set.

Conversation

izmalk commented Apr 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jahn-junior left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jahn-junior left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

izmalk commented Apr 16, 2026 •

edited

Loading