From c5bd2d42c5666974e16f37bc5c8ae197ca6fc6d1 Mon Sep 17 00:00:00 2001 From: Chris Sewell Date: Sat, 22 Jun 2024 14:50:38 +0200 Subject: [PATCH 01/10] [docs] improve RTD version selector (#12460) ensure the border-radius is applied correctly --- doc/_themes/sphinx13/static/sphinx13.css | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/doc/_themes/sphinx13/static/sphinx13.css b/doc/_themes/sphinx13/static/sphinx13.css index ba3bcf474b8..b4e040d7c0c 100644 --- a/doc/_themes/sphinx13/static/sphinx13.css +++ b/doc/_themes/sphinx13/static/sphinx13.css @@ -10,6 +10,7 @@ --colour-todo-bg: #e0c7ff; --colour-text: #333; --colour-links-light: #057; + --admonition-radius: 3px; } body { @@ -339,7 +340,7 @@ div.admonition, div.warning { font-size: 0.9em; margin: 1em 0 1em 0; border: 1px solid #86989B; - border-radius: 3px; + border-radius: var(--admonition-radius); background-color: #f7f7f7; padding: 1rem; } @@ -359,7 +360,7 @@ div.warning > p.admonition-title { background-color: #dddddd; margin: -1rem -1rem 0.8rem -1rem; padding: 0.3rem 1rem; - border-radius: 3px 3px 0 0; + border-radius: var(--admonition-radius) var(--admonition-radius) 0 0; } div.important > p.admonition-title, @@ -427,18 +428,19 @@ div.viewcode-block:target { .rst-versions.rst-badge { background-color: #f7f7f7; border: 1px solid var(--colour-sphinx-blue); - border-radius: 3px; + border-radius: var(--admonition-radius); color: var(--colour-sphinx-blue); } .rst-versions .rst-current-version { background-color: #f7f7f7; - border-radius: 3px 3px 0 0; + border-radius: var(--admonition-radius); color: var(--colour-sphinx-blue); } .rst-versions .rst-current-version .fa { color: var(--colour-sphinx-blue); } .rst-versions .rst-other-versions { + border-radius: 0 0 var(--admonition-radius) var(--admonition-radius); border-top: 1px solid var(--colour-sphinx-blue); background-color: #f7f7f7; color: var(--colour-text); From bcf32428c8cfb49ddd4ade8305dbe99f7689db8b Mon Sep 17 00:00:00 2001 From: Chris Sewell Date: Sat, 22 Jun 2024 15:32:06 +0200 Subject: [PATCH 02/10] [docs] Improve sidebar (#12461) - Remove "Site navigation" header - this is already contextually clear (especially since separators were added in #12439) - Hide "On this page" if `display_toc is False` - Format "On this page" header similar to top-level site-nav sections --- doc/_themes/sphinx13/layout.html | 11 ++++++----- doc/_themes/sphinx13/static/sphinx13.css | 3 ++- 2 files changed, 8 insertions(+), 6 deletions(-) diff --git a/doc/_themes/sphinx13/layout.html b/doc/_themes/sphinx13/layout.html index e8176da1713..e9b2078f731 100644 --- a/doc/_themes/sphinx13/layout.html +++ b/doc/_themes/sphinx13/layout.html @@ -34,12 +34,13 @@

{{ _('Navigation') }}

diff --git a/doc/_themes/sphinx13/static/sphinx13.css b/doc/_themes/sphinx13/static/sphinx13.css index b4e040d7c0c..633a66a1719 100644 --- a/doc/_themes/sphinx13/static/sphinx13.css +++ b/doc/_themes/sphinx13/static/sphinx13.css @@ -110,7 +110,8 @@ div.sphinxsidebar input { } div.sphinxsidebar h3 { - font-size: 1.5em; + font-size: 1.2em; + font-weight: 300; margin-top: 0; margin-bottom: 0.5em; padding-top: 0.5em; From a1bb1656858380da3d4a7bc1b3ccf5424592ddbb Mon Sep 17 00:00:00 2001 From: Chris Sewell Date: Sat, 22 Jun 2024 20:48:18 +0200 Subject: [PATCH 03/10] [docs] Add Github repo icon-link to topbar (#12462) Add a link to sphinx-doc/sphinx, via an icon on the right of the top-bar --- doc/_themes/sphinx13/layout.html | 30 ++++++++++++++++++++---- doc/_themes/sphinx13/static/sphinx13.css | 27 ++++++++++++++++++--- 2 files changed, 50 insertions(+), 7 deletions(-) diff --git a/doc/_themes/sphinx13/layout.html b/doc/_themes/sphinx13/layout.html index e9b2078f731..765e1784439 100644 --- a/doc/_themes/sphinx13/layout.html +++ b/doc/_themes/sphinx13/layout.html @@ -10,10 +10,17 @@ {% block header %}
- - logo - -

Sphinx

+
+ + logo + +

Sphinx

+
+
+ + {{ github_icon() }} + +
{% endblock %} @@ -60,3 +67,18 @@

{{ _('On this page') }}

{% trans sphinx_version=sphinx_version|e %}Created using Sphinx {{ sphinx_version }}.{% endtrans %}
{%- endblock %} + +{% macro github_icon() %} + + + +{% endmacro %} diff --git a/doc/_themes/sphinx13/static/sphinx13.css b/doc/_themes/sphinx13/static/sphinx13.css index 633a66a1719..35c7cbcbb19 100644 --- a/doc/_themes/sphinx13/static/sphinx13.css +++ b/doc/_themes/sphinx13/static/sphinx13.css @@ -23,21 +23,30 @@ body { display: flex; column-gap: 1em; align-items: center; + justify-content: space-between; width: 100%; background-color: var(--colour-sphinx-blue); padding: 10px 20px; box-sizing: border-box; } -.pageheader a { +.pageheader .brand { + display: flex; + align-items: baseline; + column-gap: 1em; + color: white; + text-decoration: none; +} + +.pageheader .brand a { width: 2em; } -.pageheader img { +.pageheader .brand img { filter: invert(1) drop-shadow(1px 1px 2px black); } -.pageheader h1{ +.pageheader .brand h1 { color: white; margin: 0; font-weight: 400; @@ -45,6 +54,18 @@ body { line-height: 1; } +.pageheader .icons a { + color: white; +} + +.pageheader .icons a:hover { + color: rgba(255, 255, 255, 0.8); +} + +.pageheader .icons svg { + height: 1.6em; +} + div.document { display: flex; margin: 0 0.5em; From be92d6545a48f8e6248c177f4dc345e6255d4c6b Mon Sep 17 00:00:00 2001 From: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com> Date: Sun, 23 Jun 2024 00:04:52 +0200 Subject: [PATCH 04/10] DOC: Reduce horizontal padding on small screens (#12465) Maximize used horizontal space when the screen is small. --- doc/_themes/sphinx13/static/sphinx13.css | 2 ++ 1 file changed, 2 insertions(+) diff --git a/doc/_themes/sphinx13/static/sphinx13.css b/doc/_themes/sphinx13/static/sphinx13.css index 35c7cbcbb19..49156ad56c9 100644 --- a/doc/_themes/sphinx13/static/sphinx13.css +++ b/doc/_themes/sphinx13/static/sphinx13.css @@ -442,6 +442,8 @@ div.viewcode-block:target { } div.body { border-left: none; + padding-left: 0.5em; + padding-right: 0.5em; } } From 53119133f23f5e489dac550ae3f0db417c36b0ea Mon Sep 17 00:00:00 2001 From: Chris Sewell Date: Sun, 23 Jun 2024 00:19:43 +0200 Subject: [PATCH 05/10] [docs] Keep top-bar visible (#12464) This commit ensures the top-bar is always visible, rather than being hidden on scrolling or navigating to a target. --- doc/_themes/sphinx13/static/sphinx13.css | 19 +++++++++++++++---- 1 file changed, 15 insertions(+), 4 deletions(-) diff --git a/doc/_themes/sphinx13/static/sphinx13.css b/doc/_themes/sphinx13/static/sphinx13.css index 49156ad56c9..13c451fba09 100644 --- a/doc/_themes/sphinx13/static/sphinx13.css +++ b/doc/_themes/sphinx13/static/sphinx13.css @@ -20,6 +20,10 @@ body { } .pageheader { + position: sticky; + top: 0; + z-index: 99; + height: 3rem; display: flex; column-gap: 1em; align-items: center; @@ -80,6 +84,9 @@ div.body { } div.related { + position: sticky; + top: 3rem; + z-index: 99; display: flex; color: white; background-color: var(--colour-sphinx-blue); @@ -107,16 +114,15 @@ div.sphinxsidebarwrapper { div.sphinxsidebar { position: sticky; - top: 0; + top: 4.6rem; align-self: flex-start; - height: 100vh; + height: calc(100vh - 4.6rem); width: 250px; min-width: 150px; overflow-y: auto; overflow-wrap: break-word; margin: 0; - padding-right: 15px; - padding-top: 0.5em; + padding: 0.5em 15px 0.5em 10px; font-size: 1em; } @@ -207,6 +213,11 @@ div.footer a { /* -- body styles ----------------------------------------------------------- */ +.body :target { + /* ensure targets are not obscured by top-bar when they are navigated to */ + scroll-margin-top: 6.5rem; +} + p { margin: 0.8em 0 0.5em 0; } From d42db153df3e2ea6316a58092e281be55c6c7c81 Mon Sep 17 00:00:00 2001 From: James Addison <55152140+jayaddison@users.noreply.github.com> Date: Sat, 22 Jun 2024 23:23:04 +0100 Subject: [PATCH 06/10] [ci] Ensure files within tests/js trigger NodeJS tests (#12445) Ensure that any changes to the JS tests, introduced in PR/commit pushes, re-runs the relevant GitHub Actions workflow. --- .github/workflows/nodejs.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/nodejs.yml b/.github/workflows/nodejs.yml index 12b9e61d0fc..b7f6f21bd8d 100644 --- a/.github/workflows/nodejs.yml +++ b/.github/workflows/nodejs.yml @@ -5,7 +5,7 @@ on: paths: - ".github/workflows/nodejs.yml" - "sphinx/themes/**.js" - - "tests/js" + - "tests/js/**" - "karma.conf.js" - "package.json" - "package-lock.json" @@ -13,7 +13,7 @@ on: paths: - ".github/workflows/nodejs.yml" - "sphinx/themes/**.js" - - "tests/js" + - "tests/js/**" - "karma.conf.js" - "package.json" - "package-lock.json" From 2ccae70089a883f8eb057f4a736281b6f361a99d Mon Sep 17 00:00:00 2001 From: Rafael Fontenelle Date: Mon, 24 Jun 2024 09:48:54 -0300 Subject: [PATCH 07/10] [docs] Fix typos in autodoc.rst (#12469) --- doc/usage/extensions/autodoc.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/doc/usage/extensions/autodoc.rst b/doc/usage/extensions/autodoc.rst index a5ddc418f4d..d216d37029a 100644 --- a/doc/usage/extensions/autodoc.rst +++ b/doc/usage/extensions/autodoc.rst @@ -55,8 +55,8 @@ Ensuring the code can be imported ................................. :mod:`~sphinx.ext.autodoc` analyses the code and docstrings by introspection after -importing the modules. For importing to work. you have to make sure that your -modules can be found by sphinx and that dependencies can be resolved (if your +importing the modules. For importing to work, you have to make sure that your +modules can be found by Sphinx and that dependencies can be resolved (if your module does ``import foo``, but ``foo`` is not available in the python environment that Sphinx runs in, your module import will fail). @@ -65,16 +65,16 @@ There are two ways to ensure this: 1. Use an environment that contains your package and Sphinx. This can e.g. be your local dev environment (with an editable install), or an environment in CI in which you install Sphinx and your package. The regular installation process - ensures that your package can be found by sphinx and that all dependencies are + ensures that your package can be found by Sphinx and that all dependencies are available. 2. It is alternatively possible to patch the Sphinx run so that it can operate - directly on the sources; e.g. if you want to be able to do a sphinx build from a + directly on the sources; e.g. if you want to be able to do a Sphinx build from a source checkout. - Patch :data:`sys.path` in your Sphinx :file:`conf.py` to include the folder of your sources. E.g. if you have a repository structure with :file:`doc/conf.py` - and your package is at :file:`src/mypackage`, then you sould add:: + and your package is at :file:`src/mypackage`, then you should add:: sys.path.insert(0, os.path.abspath('../src')) From 6b237d9a70d19fb2992d3e9fe163f0bd91c43344 Mon Sep 17 00:00:00 2001 From: James Addison <55152140+jayaddison@users.noreply.github.com> Date: Mon, 24 Jun 2024 18:26:24 +0100 Subject: [PATCH 08/10] [linkcheck] Allow integer for `linkcheck_rate_limit_timeout` (#12470) Eliminate type-related warnings when users configure a valid integer value for the `linkcheck_rate_limit_timeout` config setting. Co-authored-by: Chris Sewell --- CHANGES.rst | 3 +++ doc/usage/configuration.rst | 4 ++-- sphinx/builders/linkcheck.py | 2 +- tests/test_builders/test_build_linkcheck.py | 8 +++++--- 4 files changed, 11 insertions(+), 6 deletions(-) diff --git a/CHANGES.rst b/CHANGES.rst index 0a31a6746bd..be3293da1e6 100644 --- a/CHANGES.rst +++ b/CHANGES.rst @@ -58,6 +58,9 @@ Bugs fixed Patch by Bénédikt Tran. * #12220: Fix loading custom template translations for ``en`` locale. Patch by Nicolas Peugnet. +* #12459: Add valid-type arguments to the ``linkcheck_rate_limit_timeout`` + configuration setting. + Patch by James Addison. Improvements ------------ diff --git a/doc/usage/configuration.rst b/doc/usage/configuration.rst index a27107f86cc..795dc42b151 100644 --- a/doc/usage/configuration.rst +++ b/doc/usage/configuration.rst @@ -2950,8 +2950,8 @@ Options for the linkcheck builder Otherwise, ``linkcheck`` waits for a minute before to retry and keeps doubling the wait time between attempts until it succeeds or exceeds the - ``linkcheck_rate_limit_timeout``. By default, the timeout is 300 seconds - and custom timeouts should be given in seconds. + ``linkcheck_rate_limit_timeout``. By default, the timeout is 300 seconds. + Custom timeouts should be given as a number of seconds. .. _Retry-After: https://datatracker.ietf.org/doc/html/rfc7231#section-7.1.3 diff --git a/sphinx/builders/linkcheck.py b/sphinx/builders/linkcheck.py index 42be5897475..266c964ae36 100644 --- a/sphinx/builders/linkcheck.py +++ b/sphinx/builders/linkcheck.py @@ -708,7 +708,7 @@ def setup(app: Sphinx) -> ExtensionMetadata: # commonly used for dynamic pages app.add_config_value('linkcheck_anchors_ignore', ['^!'], '') app.add_config_value('linkcheck_anchors_ignore_for_url', (), '', (tuple, list)) - app.add_config_value('linkcheck_rate_limit_timeout', 300.0, '') + app.add_config_value('linkcheck_rate_limit_timeout', 300.0, '', (int, float)) app.add_config_value('linkcheck_allow_unauthorized', True, '') app.add_config_value('linkcheck_report_timeouts_as_broken', True, '', bool) diff --git a/tests/test_builders/test_build_linkcheck.py b/tests/test_builders/test_build_linkcheck.py index 3d048c774e9..17198800031 100644 --- a/tests/test_builders/test_build_linkcheck.py +++ b/tests/test_builders/test_build_linkcheck.py @@ -936,21 +936,23 @@ def test_limit_rate_doubles_previous_wait_time(app: Sphinx) -> None: assert next_check == 120.0 -@pytest.mark.sphinx(confoverrides={'linkcheck_rate_limit_timeout': 90.0}) -def test_limit_rate_clips_wait_time_to_max_time(app: Sphinx) -> None: +@pytest.mark.sphinx(confoverrides={'linkcheck_rate_limit_timeout': 90}) +def test_limit_rate_clips_wait_time_to_max_time(app: Sphinx, warning: StringIO) -> None: rate_limits = {"localhost": RateLimit(60.0, 0.0)} worker = HyperlinkAvailabilityCheckWorker(app.config, Queue(), Queue(), rate_limits) with mock.patch('time.time', return_value=0.0): next_check = worker.limit_rate(FakeResponse.url, FakeResponse.headers.get("Retry-After")) assert next_check == 90.0 + assert warning.getvalue() == '' @pytest.mark.sphinx(confoverrides={'linkcheck_rate_limit_timeout': 90.0}) -def test_limit_rate_bails_out_after_waiting_max_time(app: Sphinx) -> None: +def test_limit_rate_bails_out_after_waiting_max_time(app: Sphinx, warning: StringIO) -> None: rate_limits = {"localhost": RateLimit(90.0, 0.0)} worker = HyperlinkAvailabilityCheckWorker(app.config, Queue(), Queue(), rate_limits) next_check = worker.limit_rate(FakeResponse.url, FakeResponse.headers.get("Retry-After")) assert next_check is None + assert warning.getvalue() == '' @mock.patch('sphinx.util.requests.requests.Session.get_adapter') From a0610f4f3361a5e9b249a81b9cad8f6820543e24 Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Tue, 25 Jun 2024 09:37:05 +0200 Subject: [PATCH 09/10] Bump mypy from 1.10.0 to 1.10.1 (#12475) --- pyproject.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pyproject.toml b/pyproject.toml index 73e48555fd4..e1f5a2e79c0 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -84,7 +84,7 @@ docs = [ lint = [ "flake8>=3.5.0", "ruff==0.4.7", - "mypy==1.10.0", + "mypy==1.10.1", "sphinx-lint", "types-docutils", "types-requests", From b70578f80c78b00c6571203f3204126742367bce Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Tue, 25 Jun 2024 09:42:31 +0200 Subject: [PATCH 10/10] Bump ruff from 0.4.7 to 0.4.10 (#12452) --- pyproject.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pyproject.toml b/pyproject.toml index e1f5a2e79c0..bfe56b2e58d 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -83,7 +83,7 @@ docs = [ ] lint = [ "flake8>=3.5.0", - "ruff==0.4.7", + "ruff==0.4.10", "mypy==1.10.1", "sphinx-lint", "types-docutils",