Skip to content

Commit 282d525

Browse files
committed
Merge tag '11.5.0' into rel
2 parents 1c75215 + 0d6deed commit 282d525

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

52 files changed

+264
-439
lines changed

CHANGELOG.rst

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,24 @@
1+
Version 11.5.0
2+
--------------
3+
4+
:Date: August 13, 2024
5+
6+
* `@humitos <https://github.com/humitos>`__: Docs: simplify repdroducible guide (`#11535 <https://github.com/readthedocs/readthedocs.org/pull/11535>`__)
7+
* `@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>`__)
8+
* `@humitos <https://github.com/humitos>`__: Analytics: remove GA (`#11532 <https://github.com/readthedocs/readthedocs.org/pull/11532>`__)
9+
* `@plaindocs <https://github.com/plaindocs>`__: Post merge fixes (`#11530 <https://github.com/readthedocs/readthedocs.org/pull/11530>`__)
10+
* `@stsewd <https://github.com/stsewd>`__: Settings: explicitly set password hashers (`#11523 <https://github.com/readthedocs/readthedocs.org/pull/11523>`__)
11+
* `@humitos <https://github.com/humitos>`__: Notifications: render the URL for account using Django template tag (`#11521 <https://github.com/readthedocs/readthedocs.org/pull/11521>`__)
12+
* `@stsewd <https://github.com/stsewd>`__: Remote repository: fix slow query (`#11518 <https://github.com/readthedocs/readthedocs.org/pull/11518>`__)
13+
* `@stsewd <https://github.com/stsewd>`__: Docs: update API V3 docs about authentication (`#11517 <https://github.com/readthedocs/readthedocs.org/pull/11517>`__)
14+
* `@humitos <https://github.com/humitos>`__: Docs: remove "Canonical URLs" guide (`#11516 <https://github.com/readthedocs/readthedocs.org/pull/11516>`__)
15+
* `@humitos <https://github.com/humitos>`__: Release 11.4.0 (`#11515 <https://github.com/readthedocs/readthedocs.org/pull/11515>`__)
16+
* `@humitos <https://github.com/humitos>`__: Addons: add a notification on each Sphinx build (`#11514 <https://github.com/readthedocs/readthedocs.org/pull/11514>`__)
17+
* `@plaindocs <https://github.com/plaindocs>`__: Explore an alternative way of explaining states (`#11512 <https://github.com/readthedocs/readthedocs.org/pull/11512>`__)
18+
* `@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>`__)
19+
* `@humitos <https://github.com/humitos>`__: Notifications: render the URL using Django `url` template tag (`#11465 <https://github.com/readthedocs/readthedocs.org/pull/11465>`__)
20+
* `@humitos <https://github.com/humitos>`__: APIv3: return `permissions` expandable field on projects (`#10978 <https://github.com/readthedocs/readthedocs.org/pull/10978>`__)
21+
122
Version 11.4.0
223
--------------
324

docs/conf.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -76,7 +76,7 @@
7676

7777
master_doc = "index"
7878
copyright = "Read the Docs, Inc & contributors"
79-
version = "11.4.0"
79+
version = "11.5.0"
8080
release = version
8181
exclude_patterns = ["_build", "shared", "_includes"]
8282
default_role = "obj"

docs/user/advertising/advertising-details.rst

Lines changed: 1 addition & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -107,24 +107,14 @@ Analytics
107107
---------
108108

109109
Analytics are a sensitive enough issue that they require their own section.
110-
In the spirit of full transparency, Read the Docs uses Google Analytics (GA).
111-
We go into a bit of detail on our use of GA in our :doc:`/privacy-policy`.
112110

113-
GA is a contentious issue inside Read the Docs and in our community.
111+
Google Analytics is a contentious issue inside Read the Docs and in our community.
114112
Some users are very sensitive and privacy conscious to usage of GA.
115113
Some authors want their own analytics on their docs to see the usage their docs get.
116114
The developers at Read the Docs understand that different users have different priorities
117115
and we try to respect the different viewpoints as much as possible while also accomplishing
118116
our own goals.
119117

120-
We have taken steps to address some of the privacy concerns surrounding GA.
121-
These steps apply to analytics only collected by Read the Docs,
122-
since project authors could follow a different policy if they add GA to their projects.
123-
124-
* Users can opt-out of analytics by using the Do Not Track feature of their browser.
125-
* Read the Docs instructs Google to anonymize IP addresses sent to them.
126-
* The cookie set by GA is a session (non-persistent) cookie rather than the default 2 years.
127-
128118
Why we use analytics
129119
~~~~~~~~~~~~~~~~~~~~
130120

docs/user/api/v3.rst

Lines changed: 2 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ Authentication and authorization
1515
--------------------------------
1616

1717
Requests to the Read the Docs public API are for public and private information.
18-
All endpoints require authentication.
18+
Endpoints that return public information do not require authentication.
1919

2020

2121
Token
@@ -45,16 +45,7 @@ to authenticate as a user and have the same permissions that the user itself.
4545
Session
4646
~~~~~~~
4747

48-
.. warning::
49-
50-
Authentication via session is not enabled yet.
51-
52-
Session authentication is allowed on very specific endpoints,
53-
to allow hitting the API when reading documentation.
54-
55-
When a user is trying to authenticate via session,
56-
:abbr:`CSRF (Cross-site request forgery)` check is performed.
57-
48+
Session authentication is allowed, so the API can be used by our dashboard and other internal services.
5849

5950
Resources
6051
---------

docs/user/automation-rules.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -73,11 +73,11 @@ Hide version
7373

7474
Make version public
7575
Sets the version's privacy level to public.
76-
See :ref:`versions:Privacy levels`.
76+
See :ref:`versions:Version states`.
7777

7878
Make version private
7979
Sets the version's privacy level to private.
80-
See :ref:`versions:Privacy levels`.
80+
See :ref:`versions:Version states`.
8181

8282
Set version as default
8383
Sets the version as the :term:`default version`.

docs/user/canonical-urls.rst

Lines changed: 0 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -17,11 +17,6 @@ and this is one of the suggested ways to solve it from search engines.
1717

1818
.. _canonical URL: https://developers.google.com/search/docs/advanced/crawling/consolidate-duplicate-urls
1919

20-
.. seealso::
21-
22-
:doc:`/guides/canonical-urls`
23-
More information on how to enable canonical URLs in your project.
24-
2520
How Read the Docs generates canonical URLs
2621
------------------------------------------
2722

docs/user/commercial/privacy-level.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -17,4 +17,4 @@ and changing :guilabel:`Privacy level` to `Public`.
1717
.. note::
1818

1919
To control access to the documentation itself,
20-
see :ref:`versions:privacy levels`.
20+
see :ref:`versions:Version states`.

docs/user/commercial/sharing.rst

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -35,8 +35,6 @@ Enabling sharing
3535

3636
You can always revoke access in the same panel.
3737

38-
Users can log out by using the :ref:`Log Out <versions:Logging out>` link in the RTD flyout menu.
39-
4038
Sharing methods
4139
---------------
4240

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

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -13,8 +13,6 @@ Currently, we support two different types of single sign-on:
1313
* Authentication *and* authorization are managed by the identity provider (GitHub, Bitbucket or GitLab)
1414
* Authentication (*only*) is managed by the identity provider (Google Workspace account with a verified email address)
1515

16-
Users can log out by using the :ref:`Log Out <versions:Logging out>` link in the RTD flyout menu.
17-
1816
.. _sso_git_provider:
1917

2018
Single Sign-on with GitHub, Bitbucket, or GitLab

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -62,7 +62,7 @@ Good practice ✅
6262
Renaming an article's title is great for the reader and great for SEO,
6363
but this does not have to involve the URL.
6464
* 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.
65-
* Keep development versions :ref:`hidden <versions:Hidden>` so people do not find them on search engines by mistake.
65+
* Keep development versions :ref:`hidden <versions:Version states>` so people do not find them on search engines by mistake.
6666
This is the best way to ensure that nobody links to URLs that are intended for development purposes.
6767
* Use a :ref:`version warning <versions:Version warning>` to ensure the reader is aware in case they are reading an old (archived) version.
6868

docs/user/guides/canonical-urls.rst

Lines changed: 0 additions & 58 deletions
This file was deleted.

docs/user/guides/content/index.rst

Lines changed: 0 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -5,12 +5,8 @@ How-to guides: content, themes and SEO
55
This article explains how documentation can be optimized to appear in search results,
66
ultimately increasing traffic to your docs.
77

8-
⏩️ :doc:`Enabling canonical URLs </guides/canonical-urls>`
9-
In this guide, we introduce relevant settings for enabling canonical URLs in popular documentation frameworks.
10-
118
⏩️ :doc:`Using traffic analytics </analytics>`
129
In this guide, you can learn to use Read the Docs' built-in traffic analytics for your documentation project.
13-
You will also learn how to optionally add your own Google Analytics account or completely disable Google Analytics on your project.
1410

1511
⏩️ :doc:`Managing translations for Sphinx projects </guides/manage-translations-sphinx>`
1612
This guide walks through the process needed to manage translations of your documentation.
@@ -63,7 +59,6 @@ How-to guides: content, themes and SEO
6359
Search engine optimization (SEO) for documentation projects </guides/technical-docs-seo-guide>
6460
Using traffic analytics </analytics>
6561
Using search analytics </guides/search-analytics>
66-
Enabling canonical URLs </guides/canonical-urls>
6762
Enabling offline formats </guides/enable-offline-formats>
6863
Embedding content from your documentation </guides/embedding-content>
6964
Managing translations for Sphinx projects </guides/manage-translations-sphinx>
@@ -73,5 +68,4 @@ How-to guides: content, themes and SEO
7368
Using Jupyter notebooks in Sphinx </guides/jupyter>
7469
Migrating from rST to MyST </guides/migrate-rest-myst>
7570
Adding custom CSS or JavaScript to Sphinx documentation </guides/adding-custom-css>
76-
Removing "Edit on ..." buttons from documentation </guides/remove-edit-buttons>
7771
Adding "Edit Source" links on your Sphinx theme </guides/edit-source-links-sphinx>

docs/user/guides/pull-requests.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -48,7 +48,7 @@ To change the privacy level:
4848
#. Select your option in :guilabel:`Privacy level of builds from pull requests`
4949
#. Click on :guilabel:`Save`
5050

51-
Privacy levels work the same way as :ref:`normal versions <versions:privacy levels>`.
51+
Privacy levels work the same way as :ref:`normal versions <versions:Version states>`.
5252

5353
Limitations
5454
-----------

docs/user/guides/reproducible-builds.rst

Lines changed: 20 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -12,37 +12,42 @@ so that you can focus on content.
1212
:local:
1313
:depth: 3
1414

15-
Use a ``.readthedocs.yaml`` configuration file
15+
Define OS and tool versions in the config file
1616
----------------------------------------------
1717

18-
We recommend using a :doc:`configuration file </config-file/v2>` to manage your documentation.
19-
Our config file *provides you per version settings*,
18+
We recommend defining the explicit version of the OS and tool versions used to build your documentation
19+
using the ``.readthedocs.yaml``.
20+
This file file *provides you per version settings*,
2021
and *those settings live in your Git repository*.
2122

2223
This allows you to validate changes using :doc:`pull requests </pull-requests>`,
2324
and ensures that all your versions can be rebuilt from a reproducible configuration.
2425

25-
Use a requirements file for Python dependencies
26-
-----------------------------------------------
27-
28-
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.
29-
This ensures that top-level dependencies and extensions don't change.
30-
31-
A configuration file with explicit dependencies looks like this:
3226

3327
.. code-block:: yaml
3428
:caption: .readthedocs.yaml
29+
:emphasize-lines: 5,7-8
3530
3631
version: 2
3732
33+
# Explicitly set the OS and Python versions
3834
build:
39-
os: "ubuntu-22.04"
35+
os: "ubuntu-24.04"
4036
tools:
37+
nodejs: "20"
4138
python: "3.12"
4239
43-
# Build from the docs/ directory with Sphinx
44-
sphinx:
45-
configuration: docs/conf.py
40+
Use a requirements file for Python dependencies
41+
-----------------------------------------------
42+
43+
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.
44+
This ensures that top-level dependencies and extensions don't change.
45+
46+
A configuration file with explicit dependencies looks like this:
47+
48+
.. code-block:: yaml
49+
:caption: .readthedocs.yaml
50+
:emphasize-lines: 4
4651
4752
# Explicitly set the version of Python and its requirements
4853
python:
@@ -72,14 +77,10 @@ and they can upgrade without warning if you do not pin these packages as well.
7277

7378
We recommend `pip-tools`_ to help address this problem.
7479
It allows you to specify a ``requirements.in`` file with your top-level dependencies,
75-
and it generates a ``requirements.txt`` file with the full set of transitive dependencies.
80+
and it generates a ``requirements.txt`` file with the full set of transitive dependencies pinned.
7681

7782
.. _pip-tools: https://pip-tools.readthedocs.io/en/latest/
7883

79-
✅ Good:
80-
All your transitive dependencies are defined,
81-
which ensures new package releases will not break your docs.
82-
8384
.. code-block::
8485
:caption: docs/requirements.in
8586
@@ -139,21 +140,6 @@ and it generates a ``requirements.txt`` file with the full set of transitive dep
139140
urllib3==1.26.13
140141
# via requests
141142
142-
Check list ✅
143-
-------------
144-
145-
If you followed this guide,
146-
you have :term:`pinned <pinning>`:
147-
148-
* tool versions (Python, Node)
149-
* top-level dependencies (Sphinx, Sphinx extensions)
150-
* transitive dependencies (Pytz, Jinja2)
151-
152-
This will protect your builds from failures because of a random tool or dependency update.
153-
154-
You do still need to upgrade your dependencies from time to time,
155-
but you should do that on your own schedule.
156-
157143
.. seealso::
158144

159145
:doc:`/config-file/v2`

docs/user/legal/dpa/subprocessors.rst

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@ Sub-processor list
22
==================
33

44
:Effective: April 16, 2021
5-
:Last updated: December 27, 2022
5+
:Last updated: August 9, 2024
66

77
Read the Docs for Business uses services from the following sub-processors to
88
provide documentation hosting services. This document supplements :doc:`our Data
@@ -34,8 +34,8 @@ Sendgrid, Inc.
3434
and other generated messages. The body of notification emails can include
3535
user information, including email address.
3636

37-
Google Analytics
38-
Website analtyics for dashboard and documentation sites.
37+
Plausible
38+
Website analytics for dashboard and Read the Docs owned documentation sites.
3939

4040
Stripe Inc.
4141
Subscription payment provider. Data collected can include user data necessary

0 commit comments

Comments
 (0)