This is an automated email from the ASF dual-hosted git repository.
eze pushed a commit to branch 9.2.x
in repository https://gitbox.apache.org/repos/asf/trafficserver.git
The following commit(s) were added to refs/heads/9.2.x by this push:
new 38d15bfbc3 Sphinx 8.x and sphinx-rtd-theme 3.x (#12133) (#12151)
38d15bfbc3 is described below
commit 38d15bfbc36fffdbe18d6a0c6cffa4c6f7b1a01d
Author: Brian Neradt <[email protected]>
AuthorDate: Tue Apr 1 12:37:06 2025 -0500
Sphinx 8.x and sphinx-rtd-theme 3.x (#12133) (#12151)
This updates Sphinx to version 8 and sphinx-rtd-theme to 3.x. This has
the advantage of additional warnings that can catch some of our mistakes
and adds support for building on Python 3.13.
When considering backporting, note that this requires the docs fixes
from #12132.
(cherry picked from commit c38cfb23af5d968fa8dea293086778ac81f1c425)
Doc updates to prepare for Sphinx 8 (#12132)
This fixes issues that Sphinx 8 highlights with our footnotes and
references. This patch is in preparation of updating to Sphinx 8, which
will be in a separate PR.
This patch addresses:
* The txn-box class-reference.en was referenced from multiple layers of
the txn-box toc tree, which Sphinx 8 allerted to being a problem.
Sphinx assumes a single parent for each entry in a toc. Before I
assume it silently choose one over the other. It seems not needed in
dev-guide to me, so I simply removed it from there.
* txn_box/misc.en.rst had an unreferenced footnote which this patch
removes.
* cache-architecture/architecture.en.rst had two broken footnote
references because there wasn't a space between the previous word and
the footnote. Sphinx requires this space for the footnote to work.
(cherry picked from commit dc55e46f10e783235366ed16cca17baa189e1d46)
Co-authored-by: bneradt <[email protected]>
---
doc/Pipfile | 4 ++--
doc/conf.py | 1 -
doc/developer-guide/cache-architecture/architecture.en.rst | 4 ++--
3 files changed, 4 insertions(+), 5 deletions(-)
diff --git a/doc/Pipfile b/doc/Pipfile
index ba2b3f17f3..c1c83fb3f2 100644
--- a/doc/Pipfile
+++ b/doc/Pipfile
@@ -27,9 +27,9 @@ verify_ssl = true
# If not, we will often face issues when Sphinx updates their version before
# sphinx-rtd-theme has had time to update their component for the new sphinx
# version.
-sphinx = "==6.1.3"
+sphinx = "==8.2.3"
-sphinx-rtd-theme = ">=1.*"
+sphinx-rtd-theme = "==3.*"
sphinxcontrib-jquery = "*"
sphinxcontrib-plantuml = "*"
# i18n
diff --git a/doc/conf.py b/doc/conf.py
index 4c226278fb..dc88a505ab 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -145,7 +145,6 @@ else:
try:
import sphinx_rtd_theme
html_theme = 'sphinx_rtd_theme'
- html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
except Exception:
pass
# End of HACK
diff --git a/doc/developer-guide/cache-architecture/architecture.en.rst
b/doc/developer-guide/cache-architecture/architecture.en.rst
index 7e9bb4a6f7..7ea5358202 100644
--- a/doc/developer-guide/cache-architecture/architecture.en.rst
+++ b/doc/developer-guide/cache-architecture/architecture.en.rst
@@ -390,7 +390,7 @@ if needed to store the object.
``Doc`` layout 3.2.0
This had the problem that with only one fragment table it could not be reliable
-for objects with more than one alternate[#multiple-alternates]_. Therefore, the
+for objects with more than one alternate [#multiple-alternates]_. Therefore,
the
fragment data was moved from being a separate variable length section of the
metadata to being directly incorporated in to the
:cpp:class:`CacheHTTPInfoVector`,
yielding a layout of the following form.
@@ -720,7 +720,7 @@ The set of things which can affect cacheability are:
* Plugin operations.
The initial internal checks, along with their :file:`records.config`
-overrides[#cacheability-overrides]_, are done in
``HttpTransact::is_request_cache_lookupable``.
+overrides [#cacheability-overrides]_, are done in
``HttpTransact::is_request_cache_lookupable``.
The checks that are done are:
