feat(docs): enable Palewire extension defaults

AGENTS.md

@@ -49,8 +49,13 @@ configure an AWS OIDC role with `DOCS_AWS_ROLE_ARN` and `DOCS_AWS_REGION`, and
 set the `DOCS_DEPLOY_ENABLED` repository variable to `true`.
 
 When instantiating the template, replace the distribution placeholder in
-`docs/conf.py`, set the Palewire theme canonical and base URLs, and add an API
-reference page using autosummary for the package's public modules. Add
+`docs/conf.py`, set `html_baseurl` to the production documentation URL, and
+add an API reference page using autosummary for the package's public modules.
+The `palewire` extension derives the canonical theme URL from `html_baseurl`
+and provides the `wide` layout and `sidebar` navigation presets; adjust those
+settings only when the project needs a different presentation. For a brand-new,
+simpler documentation project, `uvx sphinx-palewire-theme init` is an optional
+shortcut, not a replacement for this template's richer configuration. Add
 host-specific linkcheck exclusions only for documented, reproducibly unstable
 URLs.
 

CHANGELOG.md

@@ -16,6 +16,21 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ### Security
 
+## [2.1.1] - 2026-08-25
+
+### Added
+
+### Changed
+
+- Enable the Palewire Sphinx extension defaults in the template and document
+  its `html_baseurl` configuration ([#278]).
+
+### Fixed
+
+### Removed
+
+### Security
+
 ## [2.1.0] - 2026-08-23
 
 ### Added
@@ -44,7 +59,8 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ### Security
 
-[Unreleased]: https://github.com/palewire/python-open-source-template/compare/2.1.0...HEAD
+[Unreleased]: https://github.com/palewire/python-open-source-template/compare/2.1.1...HEAD
+[2.1.1]: https://github.com/palewire/python-open-source-template/compare/2.1.0...2.1.1
 [2.1.0]: https://github.com/palewire/python-open-source-template/compare/2.0.0...2.1.0
 [#261]: https://github.com/palewire/python-open-source-template/pull/261
 [#262]: https://github.com/palewire/python-open-source-template/pull/262
@@ -59,3 +75,4 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 [#271]: https://github.com/palewire/python-open-source-template/pull/271
 [#272]: https://github.com/palewire/python-open-source-template/pull/272
 [#273]: https://github.com/palewire/python-open-source-template/pull/273
+[#278]: https://github.com/palewire/python-open-source-template/pull/278

TEMPLATE_SETUP.md

@@ -11,7 +11,10 @@ Complete this checklist before the first release.
 
 ## Documentation
 
-- [ ] Replace the distribution placeholder and production URLs in `docs/conf.py`.
+- [ ] Replace the distribution placeholder and set `html_baseurl` to the
+      production documentation URL in `docs/conf.py`. The `palewire` extension
+      derives the canonical theme URL from it and provides the `wide` layout and
+      `sidebar` navigation presets, which you can adjust for the project.
 - [ ] Add an autosummary-based API reference for public modules.
 - [ ] Configure S3 deployment through the protected `docs-production`
       environment, AWS OIDC variables, and `DOCS_DEPLOY_ENABLED=true`.

docs/conf.py

@@ -19,6 +19,7 @@
 pygments_style = "sphinx"
 
 extensions = [
+    "palewire",
     "myst_parser",
     "sphinx.ext.autodoc",
     "sphinx.ext.autosummary",
@@ -48,6 +49,8 @@
 linkcheck_retries = 2
 
 html_theme = "palewire"
-# Set these after choosing the production documentation URL:
-# html_theme_options = {"canonical_url": "https://docs.example.com/"}
+# Set this after choosing the production documentation URL. The Palewire extension
+# derives the theme canonical URL from html_baseurl.
 # html_baseurl = "https://docs.example.com/"
+palewire_layout = "wide"
+palewire_navigation = "sidebar"

pyproject.toml

@@ -67,7 +67,7 @@ docs = [
     "sphinxcontrib-mermaid",
     "sphinx_copybutton",
     "myst-parser",
-    "sphinx-palewire-theme",
+    "sphinx-palewire-theme>=0.1.8",
 ]
 notebooks = [
     "jupyterlab",