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.
When the encoding is not specified, open() may choose an encoding
based on the locale in use. That encoding may have no relationship
to the encoding of the file being opened. Use the locale from the
document settings instead, which should better match the file's
encoding.
Fixes: #24679
Edit Utilities/Sphinx/cmake.py to avoid lines longer than 79 characters
and to obey other flake8-checked style rules. This will allow using
flake8 to check for possible issues without having to wade through noise
about improper styling. (Also, of course, consistent styling is
beneficial in its own right.)
Port all uses of old-style % string formatting to use f-strings. These
are generally more readable (and tend to be shorter as well).
Although this requires Python 3.6 or later, that should be available
'stock' on most or all platforms still under support, and besides, we
were already using f-strings in some places.
