From ab5d440bf7f5f6610268f67d3717879ad6a705c6 Mon Sep 17 00:00:00 2001 From: Ben Date: Tue, 25 Aug 2026 12:36:43 -0400 Subject: [PATCH 1/3] feat(docs): enable Palewire extension defaults Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- AGENTS.md | 9 +++-- TEMPLATE_SETUP.md | 5 ++- docs/conf.py | 7 ++-- pyproject.toml | 2 +- uv.lock | 88 +++++++++++++++++++++++++---------------------- 5 files changed, 63 insertions(+), 48 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index eabe0e9..5e8536d 100644 --- a/AGENTS.md +++ b/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. diff --git a/TEMPLATE_SETUP.md b/TEMPLATE_SETUP.md index 991e46f..621ba68 100644 --- a/TEMPLATE_SETUP.md +++ b/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`. diff --git a/docs/conf.py b/docs/conf.py index 9f32a5a..035b859 100644 --- a/docs/conf.py +++ b/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" diff --git a/pyproject.toml b/pyproject.toml index 9f8007f..f3fc443 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -67,7 +67,7 @@ docs = [ "sphinxcontrib-mermaid", "sphinx_copybutton", "myst-parser", - "sphinx-palewire-theme", + "sphinx-palewire-theme>=0.1.8", ] notebooks = [ "jupyterlab", diff --git a/uv.lock b/uv.lock index 0442d55..44afec2 100644 --- a/uv.lock +++ b/uv.lock @@ -660,7 +660,7 @@ name = "cryptography" version = "50.0.0" source = { registry = "https://pypi.org/simple" } dependencies = [ - { name = "cffi", marker = "platform_python_implementation != 'PyPy' and sys_platform != 'emscripten' and sys_platform != 'win32'" }, + { name = "cffi", marker = "platform_python_implementation != 'PyPy'" }, ] sdist = { url = "https://files.pythonhosted.org/packages/de/41/6cbdcf9142d00fe82836fbb51e503e58088575cf7a0fe1dbff6695bf0840/cryptography-50.0.0.tar.gz", hash = "sha256:eeac2acb5a20ed25e0ad6d1df9891a520b78b404266b6d11778f25d5d691a6c9", size = 880201, upload-time = "2026-07-31T14:25:10.11Z" } wheels = [ @@ -1010,7 +1010,7 @@ name = "importlib-metadata" version = "9.0.0" source = { registry = "https://pypi.org/simple" } dependencies = [ - { name = "zipp", marker = "python_full_version < '3.12'" }, + { name = "zipp" }, ] sdist = { url = "https://files.pythonhosted.org/packages/a9/01/15bb152d77b21318514a96f43af312635eb2500c96b55398d020c93d86ea/importlib_metadata-9.0.0.tar.gz", hash = "sha256:a4f57ab599e6a2e3016d7595cfd72eb4661a5106e787a95bcc90c7105b831efc", size = 56405, upload-time = "2026-03-20T06:42:56.999Z" } wheels = [ @@ -2000,7 +2000,7 @@ name = "pexpect" version = "4.9.0" source = { registry = "https://pypi.org/simple" } dependencies = [ - { name = "ptyprocess", marker = "sys_platform != 'emscripten' and sys_platform != 'win32'" }, + { name = "ptyprocess" }, ] sdist = { url = "https://files.pythonhosted.org/packages/42/92/cc564bf6381ff43ce1f4d06852fc19a2f11d180f23dc32d9588bee2f149d/pexpect-4.9.0.tar.gz", hash = "sha256:ee7d41123f3c9911050ea2c2dac107568dc43b2d3b0c7557a33212c398ead30f", size = 166450, upload-time = "2023-11-25T09:07:26.339Z" } wheels = [ @@ -2903,8 +2903,8 @@ name = "secretstorage" version = "3.5.0" source = { registry = "https://pypi.org/simple" } dependencies = [ - { name = "cryptography", marker = "sys_platform != 'emscripten' and sys_platform != 'win32'" }, - { name = "jeepney", marker = "sys_platform != 'emscripten' and sys_platform != 'win32'" }, + { name = "cryptography" }, + { name = "jeepney" }, ] sdist = { url = "https://files.pythonhosted.org/packages/1c/03/e834bcd866f2f8a49a85eaff47340affa3bfa391ee9912a952a1faa68c7b/secretstorage-3.5.0.tar.gz", hash = "sha256:f04b8e4689cbce351744d5537bf6b1329c6fc68f91fa666f60a380edddcd11be", size = 19884, upload-time = "2025-11-23T19:02:53.191Z" } wheels = [ @@ -2989,23 +2989,23 @@ resolution-markers = [ "python_full_version < '3.12' and sys_platform != 'emscripten' and sys_platform != 'win32'", ] dependencies = [ - { name = "alabaster", marker = "python_full_version < '3.12'" }, - { name = "babel", marker = "python_full_version < '3.12'" }, - { name = "colorama", marker = "python_full_version < '3.12' and sys_platform == 'win32'" }, - { name = "docutils", marker = "python_full_version < '3.12'" }, - { name = "imagesize", marker = "python_full_version < '3.12'" }, - { name = "jinja2", marker = "python_full_version < '3.12'" }, - { name = "packaging", marker = "python_full_version < '3.12'" }, - { name = "pygments", marker = "python_full_version < '3.12'" }, - { name = "requests", marker = "python_full_version < '3.12'" }, - { name = "roman-numerals", marker = "python_full_version < '3.12'" }, - { name = "snowballstemmer", marker = "python_full_version < '3.12'" }, - { name = "sphinxcontrib-applehelp", marker = "python_full_version < '3.12'" }, - { name = "sphinxcontrib-devhelp", marker = "python_full_version < '3.12'" }, - { name = "sphinxcontrib-htmlhelp", marker = "python_full_version < '3.12'" }, - { name = "sphinxcontrib-jsmath", marker = "python_full_version < '3.12'" }, - { name = "sphinxcontrib-qthelp", marker = "python_full_version < '3.12'" }, - { name = "sphinxcontrib-serializinghtml", marker = "python_full_version < '3.12'" }, + { name = "alabaster" }, + { name = "babel" }, + { name = "colorama", marker = "sys_platform == 'win32'" }, + { name = "docutils" }, + { name = "imagesize" }, + { name = "jinja2" }, + { name = "packaging" }, + { name = "pygments" }, + { name = "requests" }, + { name = "roman-numerals" }, + { name = "snowballstemmer" }, + { name = "sphinxcontrib-applehelp" }, + { name = "sphinxcontrib-devhelp" }, + { name = "sphinxcontrib-htmlhelp" }, + { name = "sphinxcontrib-jsmath" }, + { name = "sphinxcontrib-qthelp" }, + { name = "sphinxcontrib-serializinghtml" }, ] sdist = { url = "https://files.pythonhosted.org/packages/42/50/a8c6ccc36d5eacdfd7913ddccd15a9cee03ecafc5ee2bc40e1f168d85022/sphinx-9.0.4.tar.gz", hash = "sha256:594ef59d042972abbc581d8baa577404abe4e6c3b04ef61bd7fc2acbd51f3fa3", size = 8710502, upload-time = "2025-12-04T07:45:27.343Z" } wheels = [ @@ -3025,23 +3025,23 @@ resolution-markers = [ "python_full_version >= '3.12' and python_full_version < '3.14' and sys_platform != 'emscripten' and sys_platform != 'win32'", ] dependencies = [ - { name = "alabaster", marker = "python_full_version >= '3.12'" }, - { name = "babel", marker = "python_full_version >= '3.12'" }, - { name = "colorama", marker = "python_full_version >= '3.12' and sys_platform == 'win32'" }, - { name = "docutils", marker = "python_full_version >= '3.12'" }, - { name = "imagesize", marker = "python_full_version >= '3.12'" }, - { name = "jinja2", marker = "python_full_version >= '3.12'" }, - { name = "packaging", marker = "python_full_version >= '3.12'" }, - { name = "pygments", marker = "python_full_version >= '3.12'" }, - { name = "requests", marker = "python_full_version >= '3.12'" }, - { name = "roman-numerals", marker = "python_full_version >= '3.12'" }, - { name = "snowballstemmer", marker = "python_full_version >= '3.12'" }, - { name = "sphinxcontrib-applehelp", marker = "python_full_version >= '3.12'" }, - { name = "sphinxcontrib-devhelp", marker = "python_full_version >= '3.12'" }, - { name = "sphinxcontrib-htmlhelp", marker = "python_full_version >= '3.12'" }, - { name = "sphinxcontrib-jsmath", marker = "python_full_version >= '3.12'" }, - { name = "sphinxcontrib-qthelp", marker = "python_full_version >= '3.12'" }, - { name = "sphinxcontrib-serializinghtml", marker = "python_full_version >= '3.12'" }, + { name = "alabaster" }, + { name = "babel" }, + { name = "colorama", marker = "sys_platform == 'win32'" }, + { name = "docutils" }, + { name = "imagesize" }, + { name = "jinja2" }, + { name = "packaging" }, + { name = "pygments" }, + { name = "requests" }, + { name = "roman-numerals" }, + { name = "snowballstemmer" }, + { name = "sphinxcontrib-applehelp" }, + { name = "sphinxcontrib-devhelp" }, + { name = "sphinxcontrib-htmlhelp" }, + { name = "sphinxcontrib-jsmath" }, + { name = "sphinxcontrib-qthelp" }, + { name = "sphinxcontrib-serializinghtml" }, ] sdist = { url = "https://files.pythonhosted.org/packages/cd/bd/f08eb0f4eed5c83f1ba2a3bd18f7745a2b1525fad70660a1c00224ec468a/sphinx-9.1.0.tar.gz", hash = "sha256:7741722357dd75f8190766926071fed3bdc211c74dd2d7d4df5404da95930ddb", size = 8718324, upload-time = "2025-12-31T15:09:27.646Z" } wheels = [ @@ -3081,13 +3081,17 @@ wheels = [ [[package]] name = "sphinx-palewire-theme" -version = "0.1.3" +version = "0.1.8" source = { registry = "https://pypi.org/simple" } dependencies = [ + { name = "click" }, { name = "sphinx", version = "9.0.4", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.12'" }, { name = "sphinx", version = "9.1.0", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.12'" }, ] -sdist = { url = "https://files.pythonhosted.org/packages/62/3c/85c0e4beaaab9c4135be304878ca484ba230558b00f30a2778af925f4909/sphinx_palewire_theme-0.1.3.tar.gz", hash = "sha256:d02cfdc4b6f857de398477a85af4a7844c5eadfba252a632458ec1298e387ab8", size = 12638, upload-time = "2026-02-17T01:08:49.247Z" } +sdist = { url = "https://files.pythonhosted.org/packages/27/41/4fc699b592f8c1e4b3fdf5fc48a5c29a615d7910d45f8f5340cc2924178d/sphinx_palewire_theme-0.1.8.tar.gz", hash = "sha256:df57b99ec05aa59a395e165cc5b8d125146634fc5ce50a371cd5783f2a4049b3", size = 105206, upload-time = "2026-08-25T16:30:37.733Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/ef/26/15c8bd26934642572f3a8a3d1e61a8bd8f344f812c062bf5606f5841550d/sphinx_palewire_theme-0.1.8-py3-none-any.whl", hash = "sha256:f6174a1b556484357169f46ef1fdd2b4ae10e39743d37a0b871db6545f7bb832", size = 14576, upload-time = "2026-08-25T16:30:36.387Z" }, +] [[package]] name = "sphinxcontrib-applehelp" @@ -3886,7 +3890,7 @@ docs = [ { name = "sphinx" }, { name = "sphinx-autobuild" }, { name = "sphinx-copybutton" }, - { name = "sphinx-palewire-theme" }, + { name = "sphinx-palewire-theme", specifier = ">=0.1.8" }, { name = "sphinxcontrib-mermaid" }, ] notebooks = [ From cb15e55744eed1ba37f166cdb39728c013261d2c Mon Sep 17 00:00:00 2001 From: Ben Date: Tue, 25 Aug 2026 12:40:19 -0400 Subject: [PATCH 2/3] docs: record Palewire template defaults Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- CHANGELOG.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index b06e73a..57fc9c1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -10,6 +10,9 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). ### Changed +- Enable the Palewire Sphinx extension defaults in the template and document + its `html_baseurl` configuration ([#278]). + ### Fixed ### Removed @@ -59,3 +62,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 From 45be9f6c04b4e77bc26027bb19f178580dd0f2c5 Mon Sep 17 00:00:00 2001 From: Ben Date: Tue, 25 Aug 2026 12:41:42 -0400 Subject: [PATCH 3/3] docs: prepare 2.1.1 release notes Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- CHANGELOG.md | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 57fc9c1..9622ea6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -10,6 +10,18 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). ### Changed +### Fixed + +### Removed + +### 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]). @@ -47,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