Merge tag '11.5.0' into rel

Author: humitos

CHANGELOG.rst

@@ -1,3 +1,24 @@
+Version 11.5.0
+--------------
+
+:Date: August 13, 2024
+
+* `@humitos <https://github.com/humitos>`__: Docs: simplify repdroducible guide (`#11535 <https://github.com/readthedocs/readthedocs.org/pull/11535>`__)
+* `@github-actions[bot] <https://github.com/github-actions[bot]>`__: Dependencies: all packages updated via pip-tools (`#11534 <https://github.com/readthedocs/readthedocs.org/pull/11534>`__)
+* `@humitos <https://github.com/humitos>`__: Analytics: remove GA (`#11532 <https://github.com/readthedocs/readthedocs.org/pull/11532>`__)
+* `@plaindocs <https://github.com/plaindocs>`__: Post merge fixes (`#11530 <https://github.com/readthedocs/readthedocs.org/pull/11530>`__)
+* `@stsewd <https://github.com/stsewd>`__: Settings: explicitly set password hashers (`#11523 <https://github.com/readthedocs/readthedocs.org/pull/11523>`__)
+* `@humitos <https://github.com/humitos>`__: Notifications: render the URL for account using Django template tag (`#11521 <https://github.com/readthedocs/readthedocs.org/pull/11521>`__)
+* `@stsewd <https://github.com/stsewd>`__: Remote repository: fix slow query (`#11518 <https://github.com/readthedocs/readthedocs.org/pull/11518>`__)
+* `@stsewd <https://github.com/stsewd>`__: Docs: update API V3 docs about authentication (`#11517 <https://github.com/readthedocs/readthedocs.org/pull/11517>`__)
+* `@humitos <https://github.com/humitos>`__: Docs: remove "Canonical URLs" guide (`#11516 <https://github.com/readthedocs/readthedocs.org/pull/11516>`__)
+* `@humitos <https://github.com/humitos>`__: Release 11.4.0 (`#11515 <https://github.com/readthedocs/readthedocs.org/pull/11515>`__)
+* `@humitos <https://github.com/humitos>`__: Addons: add a notification on each Sphinx build (`#11514 <https://github.com/readthedocs/readthedocs.org/pull/11514>`__)
+* `@plaindocs <https://github.com/plaindocs>`__: Explore an alternative way of explaining states (`#11512 <https://github.com/readthedocs/readthedocs.org/pull/11512>`__)
+* `@github-actions[bot] <https://github.com/github-actions[bot]>`__: Dependencies: all packages updated via pip-tools (`#11511 <https://github.com/readthedocs/readthedocs.org/pull/11511>`__)
+* `@humitos <https://github.com/humitos>`__: Notifications: render the URL using Django `url` template tag (`#11465 <https://github.com/readthedocs/readthedocs.org/pull/11465>`__)
+* `@humitos <https://github.com/humitos>`__: APIv3: return `permissions` expandable field on projects (`#10978 <https://github.com/readthedocs/readthedocs.org/pull/10978>`__)
+
 Version 11.4.0
 --------------
 

docs/conf.py

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

docs/user/advertising/advertising-details.rst

@@ -107,24 +107,14 @@ Analytics
 ---------
 
 Analytics are a sensitive enough issue that they require their own section.
-In the spirit of full transparency, Read the Docs uses Google Analytics (GA).
-We go into a bit of detail on our use of GA in our :doc:`/privacy-policy`.
 
-GA is a contentious issue inside Read the Docs and in our community.
+Google Analytics is a contentious issue inside Read the Docs and in our community.
 Some users are very sensitive and privacy conscious to usage of GA.
 Some authors want their own analytics on their docs to see the usage their docs get.
 The developers at Read the Docs understand that different users have different priorities
 and we try to respect the different viewpoints as much as possible while also accomplishing
 our own goals.
 
-We have taken steps to address some of the privacy concerns surrounding GA.
-These steps apply to analytics only collected by Read the Docs,
-since project authors could follow a different policy if they add GA to their projects.
-
-* Users can opt-out of analytics by using the Do Not Track feature of their browser.
-* Read the Docs instructs Google to anonymize IP addresses sent to them.
-* The cookie set by GA is a session (non-persistent) cookie rather than the default 2 years.
-
 Why we use analytics
 ~~~~~~~~~~~~~~~~~~~~
 

docs/user/api/v3.rst

@@ -15,7 +15,7 @@ Authentication and authorization
 --------------------------------
 
 Requests to the Read the Docs public API are for public and private information.
-All endpoints require authentication.
+Endpoints that return public information do not require authentication.
 
 
 Token
@@ -45,16 +45,7 @@ to authenticate as a user and have the same permissions that the user itself.
 Session
 ~~~~~~~
 
-.. warning::
-
-   Authentication via session is not enabled yet.
-
-Session authentication is allowed on very specific endpoints,
-to allow hitting the API when reading documentation.
-
-When a user is trying to authenticate via session,
-:abbr:`CSRF (Cross-site request forgery)` check is performed.
-
+Session authentication is allowed, so the API can be used by our dashboard and other internal services.
 
 Resources
 ---------

docs/user/automation-rules.rst

@@ -73,11 +73,11 @@ Hide version
 
 Make version public
   Sets the version's privacy level to public.
-  See :ref:`versions:Privacy levels`.
+  See :ref:`versions:Version states`.
 
 Make version private
   Sets the version's privacy level to private.
-  See :ref:`versions:Privacy levels`.
+  See :ref:`versions:Version states`.
 
 Set version as default
   Sets the version as the :term:`default version`.

docs/user/canonical-urls.rst

@@ -17,11 +17,6 @@ and this is one of the suggested ways to solve it from search engines.
 
 .. _canonical URL: https://developers.google.com/search/docs/advanced/crawling/consolidate-duplicate-urls
 
-.. seealso::
-
-   :doc:`/guides/canonical-urls`
-      More information on how to enable canonical URLs in your project.
-
 How Read the Docs generates canonical URLs
 ------------------------------------------
 

docs/user/commercial/privacy-level.rst

@@ -17,4 +17,4 @@ and changing :guilabel:`Privacy level` to `Public`.
 .. note::
 
    To control access to the documentation itself,
-   see :ref:`versions:privacy levels`.
+   see :ref:`versions:Version states`.

docs/user/commercial/sharing.rst

@@ -35,8 +35,6 @@ Enabling sharing
 
    You can always revoke access in the same panel.
 
-Users can log out by using the :ref:`Log Out <versions:Logging out>` link in the RTD flyout menu.
-
 Sharing methods
 ---------------
 

docs/user/commercial/single-sign-on.rst

@@ -13,8 +13,6 @@ Currently, we support two different types of single sign-on:
 * Authentication *and* authorization are managed by the identity provider (GitHub, Bitbucket or GitLab)
 * Authentication (*only*) is managed by the identity provider (Google Workspace account with a verified email address)
 
-Users can log out by using the :ref:`Log Out <versions:Logging out>` link in the RTD flyout menu.
-
 .. _sso_git_provider:
 
 Single Sign-on with GitHub, Bitbucket, or GitLab

docs/user/guides/best-practice/links.rst

@@ -62,7 +62,7 @@ Good practice ✅
   Renaming an article's title is great for the reader and great for SEO,
   but this does not have to involve the URL.
 * Establish your understanding of the *latest* and :term:`default version` of your documentation at the beginning. Changing their meaning is very disruptive to incoming links.
-* Keep development versions :ref:`hidden <versions:Hidden>` so people do not find them on search engines by mistake.
+* Keep development versions :ref:`hidden <versions:Version states>` so people do not find them on search engines by mistake.
   This is the best way to ensure that nobody links to URLs that are intended for development purposes.
 * Use a :ref:`version warning <versions:Version warning>` to ensure the reader is aware in case they are reading an old (archived) version.
 

docs/user/guides/canonical-urls.rst

@@ -5,12 +5,8 @@ How-to guides: content, themes and SEO
     This article explains how documentation can be optimized to appear in search results,
     ultimately increasing traffic to your docs.
 
-⏩️ :doc:`Enabling canonical URLs </guides/canonical-urls>`
-    In this guide, we introduce relevant settings for enabling canonical URLs in popular documentation frameworks.
-
 ⏩️ :doc:`Using traffic analytics </analytics>`
     In this guide, you can learn to use Read the Docs' built-in traffic analytics for your documentation project.
-    You will also learn how to optionally add your own Google Analytics account or completely disable Google Analytics on your project.
 
 ⏩️ :doc:`Managing translations for Sphinx projects </guides/manage-translations-sphinx>`
     This guide walks through the process needed to manage translations of your documentation.
@@ -63,7 +59,6 @@ How-to guides: content, themes and SEO
    Search engine optimization (SEO) for documentation projects </guides/technical-docs-seo-guide>
    Using traffic analytics </analytics>
    Using search analytics </guides/search-analytics>
-   Enabling canonical URLs </guides/canonical-urls>
    Enabling offline formats </guides/enable-offline-formats>
    Embedding content from your documentation </guides/embedding-content>
    Managing translations for Sphinx projects </guides/manage-translations-sphinx>
@@ -73,5 +68,4 @@ How-to guides: content, themes and SEO
    Using Jupyter notebooks in Sphinx </guides/jupyter>
    Migrating from rST to MyST </guides/migrate-rest-myst>
    Adding custom CSS or JavaScript to Sphinx documentation </guides/adding-custom-css>
-   Removing "Edit on ..." buttons from documentation </guides/remove-edit-buttons>
    Adding "Edit Source" links on your Sphinx theme </guides/edit-source-links-sphinx>

docs/user/guides/content/index.rst

@@ -48,7 +48,7 @@ To change the privacy level:
 #. Select your option in :guilabel:`Privacy level of builds from pull requests`
 #. Click on :guilabel:`Save`
 
-Privacy levels work the same way as :ref:`normal versions <versions:privacy levels>`.
+Privacy levels work the same way as :ref:`normal versions <versions:Version states>`.
 
 Limitations
 -----------

docs/user/guides/pull-requests.rst

@@ -12,37 +12,42 @@ so that you can focus on content.
    :local:
    :depth: 3
 
-Use a ``.readthedocs.yaml`` configuration file
+Define OS and tool versions in the config file
 ----------------------------------------------
 
-We recommend using a :doc:`configuration file </config-file/v2>` to manage your documentation.
-Our config file *provides you per version settings*,
+We recommend defining the explicit version of the OS and tool versions used to build your documentation
+using the ``.readthedocs.yaml``.
+This file file *provides you per version settings*,
 and *those settings live in your Git repository*.
 
 This allows you to validate changes using :doc:`pull requests </pull-requests>`,
 and ensures that all your versions can be rebuilt from a reproducible configuration.
 
-Use a requirements file for Python dependencies
------------------------------------------------
-
-We recommend using a Pip :ref:`requirements file <pip:requirements-file-format>` or Conda :ref:`environment file <config-file/v2:conda.environment>` to :term:`pin <pinning>` Python dependencies.
-This ensures that top-level dependencies and extensions don't change.
-
-A configuration file with explicit dependencies looks like this:
 
 .. code-block:: yaml
    :caption: .readthedocs.yaml
+   :emphasize-lines: 5,7-8
 
    version: 2
 
+   # Explicitly set the OS and Python versions
    build:
-     os: "ubuntu-22.04"
+     os: "ubuntu-24.04"
      tools:
+       nodejs: "20"
        python: "3.12"
 
-   # Build from the docs/ directory with Sphinx
-   sphinx:
-     configuration: docs/conf.py
+Use a requirements file for Python dependencies
+-----------------------------------------------
+
+We recommend using a Pip :ref:`requirements file <pip:requirements-file-format>` or Conda :ref:`environment file <config-file/v2:conda.environment>` to :term:`pin <pinning>` Python dependencies.
+This ensures that top-level dependencies and extensions don't change.
+
+A configuration file with explicit dependencies looks like this:
+
+.. code-block:: yaml
+   :caption: .readthedocs.yaml
+   :emphasize-lines: 4
 
    # Explicitly set the version of Python and its requirements
    python:
@@ -72,14 +77,10 @@ and they can upgrade without warning if you do not pin these packages as well.
 
 We recommend `pip-tools`_ to help address this problem.
 It allows you to specify a ``requirements.in`` file with your top-level dependencies,
-and it generates a ``requirements.txt`` file with the full set of transitive dependencies.
+and it generates a ``requirements.txt`` file with the full set of transitive dependencies pinned.
 
 .. _pip-tools: https://pip-tools.readthedocs.io/en/latest/
 
-✅ Good:
-    All your transitive dependencies are defined,
-    which ensures new package releases will not break your docs.
-
    .. code-block::
       :caption: docs/requirements.in
 
@@ -139,21 +140,6 @@ and it generates a ``requirements.txt`` file with the full set of transitive dep
       urllib3==1.26.13
           # via requests
 
-Check list ✅
--------------
-
-If you followed this guide,
-you have :term:`pinned <pinning>`:
-
-* tool versions (Python, Node)
-* top-level dependencies (Sphinx, Sphinx extensions)
-* transitive dependencies (Pytz, Jinja2)
-
-This will protect your builds from failures because of a random tool or dependency update.
-
-You do still need to upgrade your dependencies from time to time,
-but you should do that on your own schedule.
-
 .. seealso::
 
    :doc:`/config-file/v2`

docs/user/guides/reproducible-builds.rst

@@ -2,7 +2,7 @@ Sub-processor list
 ==================
 
 :Effective: April 16, 2021
-:Last updated: December 27, 2022
+:Last updated: August 9, 2024
 
 Read the Docs for Business uses services from the following sub-processors to
 provide documentation hosting services. This document supplements :doc:`our Data
@@ -34,8 +34,8 @@ Sendgrid, Inc.
     and other generated messages. The body of notification emails can include
     user information, including email address.
 
-Google Analytics
-    Website analtyics for dashboard and documentation sites.
+Plausible
+    Website analytics for dashboard and Read the Docs owned documentation sites.
 
 Stripe Inc.
     Subscription payment provider. Data collected can include user data necessary