In commit 038f4c12e3 (Utilities/Sphinx: Add hanging indent to version
notes, 2023-03-14, v3.27.0-rc1~322^2) we tweaked version notes to
improve readability. However, due to the way footnotes work, this
resulted in overlapping text elements when a footnote consists of a
version note. Adjust the styling to correct this issue.
These changes activate only on small screens, where "small" is defined
as <=760px, i.e. anything smaller than iPad Mini.
* Turn the sidebar into a popup (on the right) and add a hamburger
button in the header to show it.
* Split the header and footer into two lines, make the header sticky.
* Remove the prev/next links from the header.
* Put the search box first in the sidebar.
* Disable horizontal scroll of the page, enable individual scrolling
for h1, table. (Code blocks already have it).
* Allow line breaking of overly long words in the document body.
* Adjust various margins.
The sidebar popup works without JavaScript (using the "checkbox hack"),
but a bit of JavaScript is added to enable automatic closing on Esc,
on a link click and on document navigation.
* Push the footer to the bottom of the page (for short pages).
* Remove the link from the sidebar "Table of Contents" header.
* Remove text justification from TOCs and tables.
* Adjust logo position in the header.
* Restructure the navigation bar from
CMake >> [version] Documentation >> Page
to
CMake [version] >> Documentation >> Page
Sphinx 7.3 warns:
sphinx/builders/linkcheck.py:86: RemovedInSphinx80Warning:
The default value for 'linkcheck_report_timeouts_as_broken'
will change to False in Sphinx 8, ...
Configure that behavior explicitly.
The `cmake.org/get-involved` URL is more semantically meaningful than
the `cmake.org/documentation` URL to which the former now redirects as
an implementation detail.
Since commit 37e015d4a6 (Utilities/Sphinx: Refactor Sphinx reference
recording, 2023-03-08, v3.27.0-rc1~342^2~1), anchors in links to cmake
domain objects generated in html search results were missing their
object type prefix, and thus did not link to the object.
Restore our `get_objects` implementation's second tuple entry to what we
used prior to that commit. This matches what Sphinx's builtin python,
rst, and javascript modes do.
Fixes: #25067
In commit d78bfa1ecc (Utilities/Sphinx: support cmakedomain running in
parallel, 2022-10-24, v3.26.0-rc1~495^2) we declared the domain as
parallel-safe without actually implementing the required
`merge_domaindata` method. Since then, commit 37e015d4a6
(Utilities/Sphinx: Refactor Sphinx reference recording) changed how we
store resolved references, such that our separate fix for 3.26 does not
work in 3.27+.
While at it, correct a crusty comment that was overlooked during the
aforementioned refactoring.
Issue: #24076
Co-authored-by: Jared Dillard <jared.dillard@gmail.com>
Refactor commit 1f39a3cd1a (Utilities/Sphinx: Restore explicit check for
Sphinx 2.x or later) to avoid needing to suppress flake8 E402. While
ignoring it with respect to the docutils/sphinx imports and the sphinx
version check was correct, the need to disable it for the whole file was
suboptimal.
Refactoring in commit adbc8c982d (Utilities/Sphinx: Fix flake8 gripes in
cmake.py, 2023-03-13, v3.27.0-rc1~317^2) moved the assertion added by
commit cef51925a4 (Utilities/Sphinx: Require Sphinx 2.x or later,
2023-03-13, v3.27.0-rc1~317^2~2) to after imports, which is too late to
clearly reject older Sphinx versions.
