From e3a9ce924523e03a745518631eb48596ee857918 Mon Sep 17 00:00:00 2001 From: James Garner Date: Wed, 22 Jul 2026 14:21:18 +1200 Subject: [PATCH 1/8] docs: add deprecation notice --- docs/conf.py | 24 ++++++++++++++++++++++++ docs/readme.rst | 7 +++++++ 2 files changed, 31 insertions(+) diff --git a/docs/conf.py b/docs/conf.py index 55c9e89e..cdadbaad 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -308,3 +308,27 @@ def setup(app): app.add_css_file("custom.css") + app.connect("source-read", _prepend_deprecation_notice) + + +# Notice prepended to every built page so that visitors arriving on any page +# (e.g. via a search engine or a deep link) see the deprecation warning. +# We use a custom source-read hook rather than rst_prolog to avoid showing the +# notice twice on the landing page, as index.rst includes readme.rst. +_DEPRECATION_NOTICE = """\ +.. warning:: + + **python-libjuju is deprecated.** + + Charms should migrate to `Jubilant `_, Canonical's recommended library for Juju integration tests. + See `How to migrate integration tests from pytest-operator `_. + +""" + + +def _prepend_deprecation_notice(app, docname, content): + if docname in ("index", "readme"): + return + # ``content`` is a list containing a single string to make in-place modification possible. + # https://www.sphinx-doc.org/en/master/extdev/event_callbacks.html#event-source-read + content[0] = _DEPRECATION_NOTICE + content[0] diff --git a/docs/readme.rst b/docs/readme.rst index 3c656779..5405c7df 100644 --- a/docs/readme.rst +++ b/docs/readme.rst @@ -1,6 +1,13 @@ A Python library for Juju ========================= +.. warning:: + + **python-libjuju is deprecated.** + + Charms should migrate to `Jubilant `_, Canonical's recommended library for Juju integration tests. + See `How to migrate integration tests from pytest-operator `_. + Source code: https://github.com/juju/python-libjuju Bug reports: https://github.com/juju/python-libjuju/issues From 92edf41a9cdea76b6bfd5ea7b09d190d6823e3cf Mon Sep 17 00:00:00 2001 From: James Garner Date: Wed, 22 Jul 2026 14:30:22 +1200 Subject: [PATCH 2/8] docs: driveby fix formatting --- docs/readme.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/readme.rst b/docs/readme.rst index 5405c7df..4ddf950c 100644 --- a/docs/readme.rst +++ b/docs/readme.rst @@ -15,6 +15,7 @@ Bug reports: https://github.com/juju/python-libjuju/issues Documentation: https://pythonlibjuju.readthedocs.io/en/latest/ Supported Python versions: 3.8 through 3.13 + Supported Juju versions: 3.1 through 3.6 From 6d6e7b1f752a2a49da2db570ea3bbe552c9e864c Mon Sep 17 00:00:00 2001 From: James Garner Date: Wed, 22 Jul 2026 15:01:14 +1200 Subject: [PATCH 3/8] docs: document supported Ubuntu base range in the readme --- docs/readme.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/readme.rst b/docs/readme.rst index 4ddf950c..cea36d86 100644 --- a/docs/readme.rst +++ b/docs/readme.rst @@ -18,6 +18,8 @@ Supported Python versions: 3.8 through 3.13 Supported Juju versions: 3.1 through 3.6 +Supported Ubuntu bases: 12.04 LTS through 24.04 LTS + Design Notes ------------ From 64b9b199e3640988629061a2d0b9a10ec6e847d0 Mon Sep 17 00:00:00 2001 From: James Garner Date: Wed, 22 Jul 2026 15:05:06 +1200 Subject: [PATCH 4/8] docs: don't overclaim support for older Ubuntu bases --- docs/readme.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/readme.rst b/docs/readme.rst index cea36d86..fa2e7845 100644 --- a/docs/readme.rst +++ b/docs/readme.rst @@ -18,7 +18,7 @@ Supported Python versions: 3.8 through 3.13 Supported Juju versions: 3.1 through 3.6 -Supported Ubuntu bases: 12.04 LTS through 24.04 LTS +Newest supported Ubuntu base: 24.04 LTS Design Notes From beb570a366975c005f3bd3d29b4149d737efa171 Mon Sep 17 00:00:00 2001 From: James Garner Date: Wed, 22 Jul 2026 15:51:03 +1200 Subject: [PATCH 5/8] docs: use rst_prolog instead of a hook for incremental builds --- docs/conf.py | 16 +--------------- 1 file changed, 1 insertion(+), 15 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index cdadbaad..e7be4c97 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -305,30 +305,16 @@ # If true, do not generate a @detailmenu in the "Top" node's menu. # texinfo_no_detailmenu = False - def setup(app): app.add_css_file("custom.css") - app.connect("source-read", _prepend_deprecation_notice) - # Notice prepended to every built page so that visitors arriving on any page # (e.g. via a search engine or a deep link) see the deprecation warning. -# We use a custom source-read hook rather than rst_prolog to avoid showing the -# notice twice on the landing page, as index.rst includes readme.rst. -_DEPRECATION_NOTICE = """\ +rst_prolog = """ .. warning:: **python-libjuju is deprecated.** Charms should migrate to `Jubilant `_, Canonical's recommended library for Juju integration tests. See `How to migrate integration tests from pytest-operator `_. - """ - - -def _prepend_deprecation_notice(app, docname, content): - if docname in ("index", "readme"): - return - # ``content`` is a list containing a single string to make in-place modification possible. - # https://www.sphinx-doc.org/en/master/extdev/event_callbacks.html#event-source-read - content[0] = _DEPRECATION_NOTICE + content[0] From 0d22a02084b0b769d99d54f85b57a2c7965ab6f6 Mon Sep 17 00:00:00 2001 From: James Garner Date: Wed, 22 Jul 2026 15:52:11 +1200 Subject: [PATCH 6/8] docs: satisfy pre-commit --- docs/conf.py | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/conf.py b/docs/conf.py index e7be4c97..8a3847d7 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -305,9 +305,11 @@ # If true, do not generate a @detailmenu in the "Top" node's menu. # texinfo_no_detailmenu = False + def setup(app): app.add_css_file("custom.css") + # Notice prepended to every built page so that visitors arriving on any page # (e.g. via a search engine or a deep link) see the deprecation warning. rst_prolog = """ From 5bed514e3b8947499ed95a1d9ad4337fe44876df Mon Sep 17 00:00:00 2001 From: James Garner Date: Wed, 22 Jul 2026 16:13:07 +1200 Subject: [PATCH 7/8] docs: try a modified build --- .readthedocs.yaml | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 4da2dbd7..86588b53 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -14,6 +14,17 @@ build: # Older Shpinx uses imghdr that was removed in Python 3.13 # See e.g. https://github.com/python/cpython/issues/104818 python: "3.12" + jobs: + build: + # Override the default HTML build to force a full, non-incremental build. + # Read the Docs restores the previous build's cache between builds, so an + # incremental build only re-reads sources that changed -- which means our + # global deprecation notice (injected at read time) never reaches pages + # whose own source is unchanged, leaving them serving stale HTML. + # -E rebuilds the environment from scratch (re-read every source); -a + # writes all output files. Together they disable incremental builds. + html: + - python -m sphinx -T -E -a -b html -d docs/_build/doctrees -D language=en docs $READTHEDOCS_OUTPUT/html sphinx: configuration: docs/conf.py From 67c913eeedab011856d0e5a9d7c470a70a66e579 Mon Sep 17 00:00:00 2001 From: James Garner Date: Wed, 22 Jul 2026 16:51:51 +1200 Subject: [PATCH 8/8] docs: revert changes besides readme --- .readthedocs.yaml | 11 ----------- docs/conf.py | 12 ------------ 2 files changed, 23 deletions(-) diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 86588b53..4da2dbd7 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -14,17 +14,6 @@ build: # Older Shpinx uses imghdr that was removed in Python 3.13 # See e.g. https://github.com/python/cpython/issues/104818 python: "3.12" - jobs: - build: - # Override the default HTML build to force a full, non-incremental build. - # Read the Docs restores the previous build's cache between builds, so an - # incremental build only re-reads sources that changed -- which means our - # global deprecation notice (injected at read time) never reaches pages - # whose own source is unchanged, leaving them serving stale HTML. - # -E rebuilds the environment from scratch (re-read every source); -a - # writes all output files. Together they disable incremental builds. - html: - - python -m sphinx -T -E -a -b html -d docs/_build/doctrees -D language=en docs $READTHEDOCS_OUTPUT/html sphinx: configuration: docs/conf.py diff --git a/docs/conf.py b/docs/conf.py index 8a3847d7..55c9e89e 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -308,15 +308,3 @@ def setup(app): app.add_css_file("custom.css") - - -# Notice prepended to every built page so that visitors arriving on any page -# (e.g. via a search engine or a deep link) see the deprecation warning. -rst_prolog = """ -.. warning:: - - **python-libjuju is deprecated.** - - Charms should migrate to `Jubilant `_, Canonical's recommended library for Juju integration tests. - See `How to migrate integration tests from pytest-operator `_. -"""