Merge branch 'master' into doc-installing

.github/workflows/nodejs.yml

@@ -5,15 +5,15 @@ on:
     paths:
       - ".github/workflows/nodejs.yml"
       - "sphinx/themes/**.js"
-      - "tests/js"
+      - "tests/js/**"
       - "karma.conf.js"
       - "package.json"
       - "package-lock.json"
   pull_request:
     paths:
       - ".github/workflows/nodejs.yml"
       - "sphinx/themes/**.js"
-      - "tests/js"
+      - "tests/js/**"
       - "karma.conf.js"
       - "package.json"
       - "package-lock.json"

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
 ------------

doc/_themes/sphinx13/layout.html

@@ -10,10 +10,17 @@
 
 {% block header %}
 <div class="pageheader">
-  <a href="{{ pathto(root_doc)|e }}">
-    <img src="{{ pathto('_static/sphinx-logo.svg', resource=True) }}" alt="logo" />
-  </a>
-  <h1>Sphinx</h1>
+  <div class="brand">
+    <a href="{{ pathto(root_doc)|e }}">
+      <img src="{{ pathto('_static/sphinx-logo.svg', resource=True) }}" alt="logo" />
+    </a>
+    <h1>Sphinx</h1>
+  </div>
+  <div class="icons">
+    <a href="https://github.com/sphinx-doc/sphinx" title="{{ _('Source Code') }}" target="_blank">
+      {{ github_icon() }}
+    </a>
+  </div>
 </div>
 {% endblock %}
 
@@ -34,12 +41,13 @@ <h3>{{ _('Navigation') }}</h3>
 <div class="document">
   <div class="sphinxsidebar" role="navigation" aria-label="Main">
     {%- include "searchfield.html" %}
-    <div class="sphinxsidebar-navigation__contents">
-      <h3>{{ _('On this page') }}</h3>
-      {{ toc }}
-    </div>
+    {%- if display_toc %}
+      <div class="sphinxsidebar-navigation__contents">
+        <h3>{{ _('On this page') }}</h3>
+        {{ toc }}
+      </div>
+    {%- endif %}
     <div class="sphinxsidebar-navigation__pages">
-      <h3>{{ _('Site navigation') }}</h3>
       {{ toctree(includehidden=True, maxdepth=3, titles_only=True) }}
     </div>
   </div>
@@ -59,3 +67,18 @@ <h3>{{ _('Site navigation') }}</h3>
   {% trans sphinx_version=sphinx_version|e %}Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> {{ sphinx_version }}.{% endtrans %}
 </div>
 {%- endblock %}
+
+{% macro github_icon() %}
+    <svg
+    stroke="currentColor"
+    fill="currentColor"
+    stroke-width="0"
+    viewBox="0 0 16 16"
+    class="gh-source"
+  >
+    <path
+      fill-rule="evenodd"
+      d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0 0 16 8c0-4.42-3.58-8-8-8z"
+    ></path>
+  </svg>
+{% endmacro %}

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 {
@@ -19,31 +20,56 @@ body {
 }
 
 .pageheader {
+    position: sticky;
+    top: 0;
+    z-index: 99;
+    height: 3rem;
     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;
     font-size: 2em;
     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;
@@ -58,6 +84,9 @@ div.body {
 }
 
 div.related {
+    position: sticky;
+    top: 3rem;
+    z-index: 99;
     display: flex;
     color: white;
     background-color: var(--colour-sphinx-blue);
@@ -85,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;
 }
 
@@ -109,7 +137,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;
@@ -184,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;
 }
@@ -339,7 +373,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 +393,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,
@@ -419,6 +453,8 @@ div.viewcode-block:target {
     }
     div.body {
         border-left: none;
+        padding-left: 0.5em;
+        padding-right: 0.5em;
     }
 }
 
@@ -427,18 +463,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);

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
 

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'))
 

pyproject.toml

@@ -83,8 +83,8 @@ docs = [
 ]
 lint = [
     "flake8>=3.5.0",
-    "ruff==0.4.7",
-    "mypy==1.10.0",
+    "ruff==0.4.10",
+    "mypy==1.10.1",
     "sphinx-lint",
     "types-docutils",
     "types-requests",

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)
 

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')