Skip to content

Conversation

@tang-mm
Copy link
Collaborator

@tang-mm tang-mm commented Jul 29, 2025

Description

  • Migrate the Sphinx docs infrastructure to use the extension-based schema, where styling and other common templates are centralized in an imported extension. Updates are from sphinx-docs-starter-pack v1.2.0, including
    • import canonical-sphinx extension v5.1.0
    • sitemap support (/sitemap.xml available after online and local builds)
    • make commands and scripts for optional automatic quality checks: accessibility, style guide, markdown linter
  • update docs/conf.py to match the new version
  • update docs/Makefile to match the new version, existing targets remain unchanged
  • Spelling check tool changed from pyspell to vale,
    • the user wordlist renamed from docs/.sphinx/wordlist.txt --> docs/.custom_wordlist.txt
    • clean up obsolete user words and fix spelling in docs
  • remove unused dependency packages

Resolved issues

CHECKBOX-1769

Documentation

UI update (new header and slgiht styling changes):

  • before:
image
  • after: image

Tests

PR checks

tang-mm added 4 commits July 29, 2025 13:15
The starter-pack has been upgraded to the extension-based version:
more tooling supports are provided and most styling configurations are
centralized in the canonical-sphinx extension.
This upgrade uses the extension v5.1.0, and the starter-pack
1.2.0
https://github.com/canonical/sphinx-docs-starter-pack/releases/tag/1.2.0
@tang-mm tang-mm marked this pull request as draft July 29, 2025 05:39
@tang-mm
Copy link
Collaborator Author

tang-mm commented Jul 29, 2025

TODO:
- GH workflow file documentation-check.yml need to be updated
- vesion number missing in the homepage title

Fixed

@tang-mm tang-mm marked this pull request as ready for review July 29, 2025 10:30
@Hook25 Hook25 merged commit 0e0a3a0 into main Aug 8, 2025
22 of 25 checks passed
@Hook25 Hook25 deleted the CHECKBOX-1769-sphinx-docs-extension branch August 8, 2025 10:15
stanley31huang pushed a commit that referenced this pull request Aug 14, 2025
…2054)

* Migrate docs starter-pack to extension version 1.2.0

The starter-pack has been upgraded to the extension-based version:
more tooling supports are provided and most styling configurations are
centralized in the canonical-sphinx extension.
This upgrade uses the extension v5.1.0, and the starter-pack
1.2.0
https://github.com/canonical/sphinx-docs-starter-pack/releases/tag/1.2.0

* Update Makefile to the latest version

* update conf.py to latest and clean up requirements

* update spelling wordlist and doc fix

* add release version to title

* black formatting

* update doc check workflow to use new tooling

* build readthedocs only upon docs changes

* remove unused docs scripts: metrics and update
bladernr pushed a commit that referenced this pull request Aug 28, 2025
…2054)

* Migrate docs starter-pack to extension version 1.2.0

The starter-pack has been upgraded to the extension-based version:
more tooling supports are provided and most styling configurations are
centralized in the canonical-sphinx extension.
This upgrade uses the extension v5.1.0, and the starter-pack
1.2.0
https://github.com/canonical/sphinx-docs-starter-pack/releases/tag/1.2.0

* Update Makefile to the latest version

* update conf.py to latest and clean up requirements

* update spelling wordlist and doc fix

* add release version to title

* black formatting

* update doc check workflow to use new tooling

* build readthedocs only upon docs changes

* remove unused docs scripts: metrics and update
stanley31huang pushed a commit that referenced this pull request Oct 3, 2025
…2054)

* Migrate docs starter-pack to extension version 1.2.0

The starter-pack has been upgraded to the extension-based version:
more tooling supports are provided and most styling configurations are
centralized in the canonical-sphinx extension.
This upgrade uses the extension v5.1.0, and the starter-pack
1.2.0
https://github.com/canonical/sphinx-docs-starter-pack/releases/tag/1.2.0

* Update Makefile to the latest version

* update conf.py to latest and clean up requirements

* update spelling wordlist and doc fix

* add release version to title

* black formatting

* update doc check workflow to use new tooling

* build readthedocs only upon docs changes

* remove unused docs scripts: metrics and update
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants