Merge tag '10.18.0' into rel

Author: humitos

.github/workflows/pip-tools.yaml

@@ -40,7 +40,7 @@ jobs:
         run: invoke requirements.update
 
       - name: Create Pull Request
-        uses: peter-evans/create-pull-request@v5
+        uses: peter-evans/create-pull-request@v6
         with:
           add-paths: |
             requirements/*.txt

CHANGELOG.rst

@@ -1,3 +1,34 @@
+Version 10.18.0
+---------------
+
+:Date: February 06, 2024
+
+* `@dependabot[bot] <https://github.com/dependabot[bot]>`__: Bump peter-evans/create-pull-request from 5 to 6 (`#11092 <https://github.com/readthedocs/readthedocs.org/pull/11092>`__)
+* `@man-chi <https://github.com/man-chi>`__: add example list for showing basic asciidoc using Antora  (`#11091 <https://github.com/readthedocs/readthedocs.org/pull/11091>`__)
+* `@github-actions[bot] <https://github.com/github-actions[bot]>`__: Dependencies: all packages updated via pip-tools (`#11090 <https://github.com/readthedocs/readthedocs.org/pull/11090>`__)
+* `@stsewd <https://github.com/stsewd>`__: Use html_format instead of mark_safe + format (`#11086 <https://github.com/readthedocs/readthedocs.org/pull/11086>`__)
+* `@stsewd <https://github.com/stsewd>`__: Build: use version slug for get_version_slug (`#11085 <https://github.com/readthedocs/readthedocs.org/pull/11085>`__)
+* `@stsewd <https://github.com/stsewd>`__: Integrations: Don't allow webhooks without a secret (`#11083 <https://github.com/readthedocs/readthedocs.org/pull/11083>`__)
+* `@stsewd <https://github.com/stsewd>`__: Config file: add support for latest aliases (`#11081 <https://github.com/readthedocs/readthedocs.org/pull/11081>`__)
+* `@stsewd <https://github.com/stsewd>`__: Proxito: always add nginx internal path (`#11080 <https://github.com/readthedocs/readthedocs.org/pull/11080>`__)
+* `@stsewd <https://github.com/stsewd>`__: Redirects: remove unused status field (`#11079 <https://github.com/readthedocs/readthedocs.org/pull/11079>`__)
+* `@stsewd <https://github.com/stsewd>`__: Docs: fix redirects example (`#11078 <https://github.com/readthedocs/readthedocs.org/pull/11078>`__)
+* `@humitos <https://github.com/humitos>`__: Release 10.17.0 (`#11077 <https://github.com/readthedocs/readthedocs.org/pull/11077>`__)
+* `@stsewd <https://github.com/stsewd>`__: Docs: clarify search configuration patterns (`#11076 <https://github.com/readthedocs/readthedocs.org/pull/11076>`__)
+* `@humitos <https://github.com/humitos>`__: Build: add support for Ruby (`#11075 <https://github.com/readthedocs/readthedocs.org/pull/11075>`__)
+* `@humitos <https://github.com/humitos>`__: Build: update some `build.tools` versions (`#11074 <https://github.com/readthedocs/readthedocs.org/pull/11074>`__)
+* `@humitos <https://github.com/humitos>`__: Make Sphinx to share environment between commands (`#11073 <https://github.com/readthedocs/readthedocs.org/pull/11073>`__)
+* `@ericholscher <https://github.com/ericholscher>`__: Fix provier_name in notification template (`#11066 <https://github.com/readthedocs/readthedocs.org/pull/11066>`__)
+* `@humitos <https://github.com/humitos>`__: Build: don't attach notification when build failed `before_start` (`#11057 <https://github.com/readthedocs/readthedocs.org/pull/11057>`__)
+* `@humitos <https://github.com/humitos>`__: Notification: create an index for `attached_to` (`#11050 <https://github.com/readthedocs/readthedocs.org/pull/11050>`__)
+* `@stsewd <https://github.com/stsewd>`__: Redirects: fix infinite loop detection (`#11038 <https://github.com/readthedocs/readthedocs.org/pull/11038>`__)
+* `@ericholscher <https://github.com/ericholscher>`__: Release 10.15.1 (`#11034 <https://github.com/readthedocs/readthedocs.org/pull/11034>`__)
+* `@humitos <https://github.com/humitos>`__: Logging: reduce not useful lines (`#11030 <https://github.com/readthedocs/readthedocs.org/pull/11030>`__)
+* `@github-actions[bot] <https://github.com/github-actions[bot]>`__: Dependencies: all packages updated via pip-tools (`#10860 <https://github.com/readthedocs/readthedocs.org/pull/10860>`__)
+* `@stsewd <https://github.com/stsewd>`__: Fix docker setting (`#10565 <https://github.com/readthedocs/readthedocs.org/pull/10565>`__)
+* `@humitos <https://github.com/humitos>`__: Deprecation: remove code for config file v1 and default config file (`#10367 <https://github.com/readthedocs/readthedocs.org/pull/10367>`__)
+* `@benjaoming <https://github.com/benjaoming>`__: Docs: Re-scope Intersphinx article as a how-to (`#9622 <https://github.com/readthedocs/readthedocs.org/pull/9622>`__)
+
 Version 10.17.0
 ---------------
 

docs/conf.py

@@ -77,7 +77,7 @@
 
 master_doc = "index"
 copyright = "Read the Docs, Inc & contributors"
-version = "10.17.0"
+version = "10.18.0"
 release = version
 exclude_patterns = ["_build", "shared", "_includes"]
 default_role = "obj"

docs/user/config-file/v2.rst

@@ -274,18 +274,37 @@ Image names refer to the operating system Read the Docs uses to build them.
    Arbitrary Docker images are not supported.
 
 :Type: ``string``
-:Options: ``ubuntu-20.04``, ``ubuntu-22.04``
+:Options: ``ubuntu-20.04``, ``ubuntu-22.04``, ``ubuntu-lts-latest``
 :Required: ``true``
 
+.. note::
+
+   The ``ubuntu-lts-latest`` option refers to the latest Ubuntu LTS version of Ubuntu available on Read the Docs,
+   which may not match the latest Ubuntu LTS officially released.
+
+.. warning::
+
+   Using ``ubuntu-lts-latest`` may break your builds unexpectedly if your project isn't compatible with the newest Ubuntu LTS version when it's updated by Read the Docs.
+
 build.tools
 ```````````
 
 Version specifiers for each tool. It must contain at least one tool.
 
 :Type: ``dict``
-:Options: ``python``, ``nodejs``, ``rust``, ``golang``
+:Options: ``python``, ``nodejs``, ``ruby``, ``rust``, ``golang``
 :Required: ``true``
 
+.. note::
+
+   Each tool has a ``latest`` option available, which refers to the latest version available on Read the Docs,
+   which may not match the latest version officially released.
+   Versions and the ``latest`` option are updated at least once every six months to keep up with the latest releases.
+
+.. warning::
+
+   Using ``latest`` may break your builds unexpectedly if your project isn't compatible with the newest version of the tool when it's updated by Read the Docs.
+
 build.tools.python
 ``````````````````
 
@@ -301,17 +320,20 @@ You can use several interpreters and versions, from CPython, Miniconda, and Mamb
 :Type: ``string``
 :Options:
   - ``2.7``
-  - ``3`` (last stable CPython version)
+  - ``3`` (alias for the latest 3.x version available on Read the Docs)
   - ``3.6``
   - ``3.7``
   - ``3.8``
   - ``3.9``
   - ``3.10``
   - ``3.11``
   - ``3.12``
+  - ``latest`` (alias for the latest version available on Read the Docs)
   - ``miniconda3-4.7``
+  - ``miniconda-latest`` (alias for the latest version available on Read the Docs)
   - ``mambaforge-4.10``
   - ``mambaforge-22.9``
+  - ``mambaforge-latest`` (alias for the latest version available on Read the Docs)
 
 build.tools.nodejs
 ``````````````````
@@ -325,6 +347,17 @@ Node.js version to use.
    - ``18``
    - ``19``
    - ``20``
+   - ``latest`` (alias for the latest version available on Read the Docs)
+
+build.tools.ruby
+````````````````
+
+Ruby version to use.
+
+:Type: ``string``
+:Options:
+   - ``3.3``
+   - ``latest`` (alias for the latest version available on Read the Docs)
 
 build.tools.rust
 ````````````````
@@ -337,6 +370,8 @@ Rust version to use.
    - ``1.61``
    - ``1.64``
    - ``1.70``
+   - ``1.75``
+   - ``latest`` (alias for the latest version available on Read the Docs)
 
 build.tools.golang
 ``````````````````
@@ -349,6 +384,8 @@ Go version to use.
    - ``1.18``
    - ``1.19``
    - ``1.20``
+   - ``1.21``
+   - ``latest`` (alias for the latest version available on Read the Docs)
 
 build.apt_packages
 ``````````````````
@@ -657,13 +694,13 @@ Set a custom search rank over pages matching a pattern.
 :Type: ``map`` of patterns to ranks
 :Default: ``{}``
 
-Patterns are matched against the final html pages produced by the build
-(you should try to match `index.html`, not `docs/index.rst`).
-Patterns can include some special characters:
+Patterns are matched against the relative paths of the HTML files produced by the build,
+you should try to match ``index.html``, not ``docs/index.rst``, nor ``/en/latest/index.html``.
+Patterns can include one or more of the following special characters:
 
-- ``*`` matches everything
-- ``?`` matches any single character
-- ``[seq]`` matches any character in ``seq``
+- ``*`` matches everything, including slashes.
+- ``?`` matches any single character.
+- ``[seq]`` matches any character in ``seq``.
 
 The rank can be an integer number between -10 and 10 (inclusive).
 Pages with a rank closer to -10 will appear further down the list of results,
@@ -685,8 +722,10 @@ check :ref:`config-file/v2:search.ignore`.
        # Match all files under the api/v1 directory
        api/v1/*: -5
 
-       # Match all files that end with tutorial.html
-       '*/tutorial.html': 3
+       # Match all files named guides.html,
+       # two patterns are needed to match both the root and nested files.
+       'guides.html': 3
+       '*/guides.html': 3
 
 .. note::
 
@@ -706,13 +745,13 @@ Paths matched will not be included in search results.
 :Type: ``list`` of patterns
 :Default: ``['search.html', 'search/index.html', '404.html', '404/index.html']``
 
-Patterns are matched against the relative path of html files produced by the build
-(you should try to match `index.html`, not `docs/index.rst`).
-Patterns can include some special characters:
+Patterns are matched against the relative paths of the HTML files produced by the build,
+you should try to match ``index.html``, not ``docs/index.rst``, nor ``/en/latest/index.html``.
+Patterns can include one or more of the following special characters:
 
-- ``*`` matches everything
-- ``?`` matches any single character
-- ``[seq]`` matches any character in ``seq``
+- ``*`` matches everything (including slashes).
+- ``?`` matches any single character.
+- ``[seq]`` matches any character in ``seq``.
 
 .. code-block:: yaml
 
@@ -726,7 +765,9 @@ Patterns can include some special characters:
         # Ignore all files under the search/ directory
         - search/*
 
-        # Ignore all files named ref.html nested inside one or more sub-folders
+        # Ignore all files named ref.html,
+        # two patterns are needed to match both the root and nested files.
+        - 'ref.html'
         - '*/ref.html'
 
 .. code-block:: yaml

docs/user/examples.rst

@@ -32,7 +32,10 @@ Sphinx and MkDocs examples
      - Jupyter Book and Sphinx
      - `[Git] <https://github.com/readthedocs-examples/example-jupyter-book/>`__ `[Rendered] <https://example-jupyter-book.readthedocs.io/>`__
      - Jupyter Book with popular integrations configured
-
+   * - Basic AsciiDoc
+     - Antora
+     - `[Git] <https://github.com/man-chi/example-antora-basic/>`__ `[Rendered] <https://example-antora-basic.readthedocs.io/>`__
+     - Antora with asciidoctor-kroki extension configured for AsciiDoc and Diagram as Code.
 
 Real-life examples
 ------------------

docs/user/user-defined-redirects.rst

@@ -326,7 +326,7 @@ for example::
 
   Type: Exact Redirect
   From URL: /*
-  To URL: https://newdocs.example.com/
+  To URL: https://newdocs.example.com/:splat
   Force Redirect: True
 
 Users will now be redirected:

package.json

@@ -1,6 +1,6 @@
 {
   "name": "readthedocs",
-  "version": "10.17.0",
+  "version": "10.18.0",
   "description": "Read the Docs build dependencies",
   "author": "Read the Docs, Inc <[email protected]>",
   "scripts": {

readthedocs/__init__.py

@@ -1,4 +1,4 @@
 """Read the Docs."""
 
 
-__version__ = "10.17.0"
+__version__ = "10.18.0"

readthedocs/api/v2/views/integrations.py

@@ -1,6 +1,5 @@
 """Endpoints integrating with Github, Bitbucket, and other webhooks."""
 
-import datetime
 import hashlib
 import hmac
 import json
@@ -10,7 +9,6 @@
 
 import structlog
 from django.shortcuts import get_object_or_404
-from django.utils import timezone
 from django.utils.crypto import constant_time_compare
 from rest_framework import permissions, status
 from rest_framework.exceptions import NotFound, ParseError
@@ -74,14 +72,6 @@ class WebhookMixin:
     integration = None
     integration_type = None
     invalid_payload_msg = 'Payload not valid'
-    missing_secret_for_pr_events_msg = dedent(
-        """
-        This webhook doesn't have a secret configured.
-        For security reasons, webhooks without a secret can't process pull/merge request events.
-        For more information, read our blog post: https://blog.readthedocs.com/security-update-on-incoming-webhooks/.
-        """
-    ).strip()
-
     missing_secret_deprecated_msg = dedent(
         """
         This webhook doesn't have a secret configured.
@@ -116,12 +106,9 @@ def post(self, request, project_slug):
         except Project.DoesNotExist as exc:
             raise NotFound("Project not found") from exc
 
-        # Deprecate webhooks without a secret
+        # Webhooks without a secret are no longer permitted.
         # https://blog.readthedocs.com/security-update-on-incoming-webhooks/.
-        now = timezone.now()
-        deprecation_date = datetime.datetime(2024, 1, 31, tzinfo=datetime.timezone.utc)
-        is_deprecated = now >= deprecation_date
-        if is_deprecated and not self.has_secret():
+        if not self.has_secret():
             return Response(
                 {"detail": self.missing_secret_deprecated_msg},
                 status=HTTP_400_BAD_REQUEST,
@@ -418,12 +405,9 @@ def is_payload_valid(self):
         See https://developer.github.com/webhooks/securing/.
         """
         signature = self.request.headers.get(GITHUB_SIGNATURE_HEADER)
-        secret = self.get_integration().secret
-        if not secret:
-            log.debug('Skipping payload signature validation.')
-            return True
         if not signature:
             return False
+        secret = self.get_integration().secret
         msg = self.request.body.decode()
         digest = WebhookMixin.get_digest(secret, msg)
         result = hmac.compare_digest(
@@ -492,13 +476,6 @@ def handle_webhook(self):
 
         # Handle pull request events.
         if self.project.external_builds_enabled and event == GITHUB_PULL_REQUEST:
-            # Requests from anonymous users are ignored.
-            if not integration.secret:
-                return Response(
-                    {"detail": self.missing_secret_for_pr_events_msg},
-                    status=HTTP_400_BAD_REQUEST,
-                )
-
             if action in [
                 GITHUB_PULL_REQUEST_OPENED,
                 GITHUB_PULL_REQUEST_REOPENED,
@@ -598,10 +575,9 @@ def is_payload_valid(self):
         See https://docs.gitlab.com/ee/user/project/integrations/webhooks.html#secret-token.
         """
         token = self.request.headers.get(GITLAB_TOKEN_HEADER, "")
+        if not token:
+            return False
         secret = self.get_integration().secret
-        if not secret:
-            log.debug('Skipping payload signature validation.')
-            return True
         return constant_time_compare(secret, token)
 
     def get_external_version_data(self):
@@ -636,8 +612,6 @@ def handle_webhook(self):
             event=event,
         )
 
-        integration = self.get_integration()
-
         # Always update `latest` branch to point to the default branch in the repository
         # even if the event is not gonna be handled. This helps us to keep our db in sync.
         default_branch = self.data.get("project", {}).get("default_branch", None)
@@ -665,12 +639,6 @@ def handle_webhook(self):
                 raise ParseError('Parameter "ref" is required') from exc
 
         if self.project.external_builds_enabled and event == GITLAB_MERGE_REQUEST:
-            if not integration.secret:
-                return Response(
-                    {"detail": self.missing_secret_for_pr_events_msg},
-                    status=HTTP_400_BAD_REQUEST,
-                )
-
             if action in [
                 GITLAB_MERGE_REQUEST_OPEN,
                 GITLAB_MERGE_REQUEST_REOPEN,
@@ -779,12 +747,9 @@ def is_payload_valid(self):
         See https://support.atlassian.com/bitbucket-cloud/docs/manage-webhooks/#Secure-webhooks.
         """
         signature = self.request.headers.get(BITBUCKET_SIGNATURE_HEADER)
-        secret = self.get_integration().secret
-        if not secret:
-            log.debug("Skipping payload signature validation.")
-            return True
         if not signature:
             return False
+        secret = self.get_integration().secret
         msg = self.request.body.decode()
         digest = WebhookMixin.get_digest(secret, msg)
         result = hmac.compare_digest(