Merge tag '11.7.2' into rel

Author: humitos

CHANGELOG.rst

@@ -1,3 +1,19 @@
+Version 11.7.2
+--------------
+
+:Date: September 10, 2024
+
+* `@github-actions[bot] <https://github.com/github-actions[bot]>`__: Dependencies: all packages updated via pip-tools (`#11590 <https://github.com/readthedocs/readthedocs.org/pull/11590>`__)
+* `@agjohnson <https://github.com/agjohnson>`__: Update common (`#11589 <https://github.com/readthedocs/readthedocs.org/pull/11589>`__)
+* `@humitos <https://github.com/humitos>`__: Docs: final date for addons and link to blog post (`#11588 <https://github.com/readthedocs/readthedocs.org/pull/11588>`__)
+* `@humitos <https://github.com/humitos>`__: Docs: small updates to sitemaps page (`#11585 <https://github.com/readthedocs/readthedocs.org/pull/11585>`__)
+* `@stsewd <https://github.com/stsewd>`__: SAML: update docs (`#11583 <https://github.com/readthedocs/readthedocs.org/pull/11583>`__)
+* `@stsewd <https://github.com/stsewd>`__: Email: use first recipient from email object (`#11581 <https://github.com/readthedocs/readthedocs.org/pull/11581>`__)
+* `@humitos <https://github.com/humitos>`__: Release 11.7.1 (`#11580 <https://github.com/readthedocs/readthedocs.org/pull/11580>`__)
+* `@stsewd <https://github.com/stsewd>`__: Admin: set raw field for SSOIntegration (`#11572 <https://github.com/readthedocs/readthedocs.org/pull/11572>`__)
+* `@humitos <https://github.com/humitos>`__: Add project: skip config step if YAML file is present (`#11540 <https://github.com/readthedocs/readthedocs.org/pull/11540>`__)
+* `@agjohnson <https://github.com/agjohnson>`__: Standardize error template paths (`#11494 <https://github.com/readthedocs/readthedocs.org/pull/11494>`__)
+
 Version 11.7.1
 --------------
 

common

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

docs/conf.py

@@ -40,7 +40,8 @@ All projects using ``mkdocs`` :ref:`mkdocs <config-file/v2:mkdocs>` or the ``bui
 
 .. note::
 
-    Read the Docs Addons will be enabled by default for all Read the Docs projects some time in the second half of 2024.
+    Read the Docs Addons will be enabled by default for all Read the Docs projects on October 7th.
+    Read the full announcement in our `blog post <https://about.readthedocs.com/blog/2024/07/addons-by-default/>`_.
 
 Configuring Read the Docs Addons
 --------------------------------

docs/user/addons.rst

@@ -18,8 +18,8 @@ Prerequisites
 
 .. include:: /shared/organization-permissions.rst
 
-Create a new SAML application in Okta
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Create a SAML application in Okta
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 In order to enable SSO with Okta, you need to create a new SAML application in your Okta account.
 
@@ -51,56 +51,79 @@ In order to enable SSO with Okta, you need to create a new SAML application in y
 8. Select ``This is an internal app that we have created``.
 9. Click :guilabel:`Finish`.
 
-User setup
-~~~~~~~~~~
+Enable SAML on your Read the Docs organization
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Using this setup, all users who have access to the configured Okta application will automatically join to your Read the Docs organization when they sign up.
-Existing users will not be automatically joined to the organization.
+Once you have created the SAML application in Okta, you need to enable SAML on Read the Docs.
 
-You can still add outside collaborators and manage their access.
-There are two ways to manage this access:
-
-* Using :doc:`teams </guides/manage-read-the-docs-teams>` to provide access for ongoing contribution.
-* Using :doc:`sharing </commercial/sharing>` to provide short-term access requiring a login.
+1. Copy the Metadata URL from the Okta application you just created.
 
-Enabling SSO
-------------
+   * On Okta, click on the :guilabel:`Applications`.
+   * Click on the Read the Docs application.
+   * Click on the :guilabel:`Sign On` tab.
+   * Copy the :guilabel:`Metadata URL`.
 
-Enabling SSO is currently done by the Read the Docs team,
-contact :doc:`support </support>` to enable this feature for your organization.
+2. Go you your `organization's SAML settings page <https://readthedocs.com/organizations/choose/organization_saml/>`__.
+3. Paste the Metadata URL in the :guilabel:`Metadata URL` field.
+4. Leave the domain field empty.
+5. Click :guilabel:`Save`.
 
-By default, users that sign up with SAML do not have any permissions over any project.
-However, you can define which teams users will auto-join when they sign up.
+Attaching the email domain your organization uses to enforce SAML is currently done by the Read the Docs team,
+contact :doc:`support </support>` using an account that's an owner of the organization.
 
-After enabling the SAML integration,
-all users with email addresses from your configured domain will be required to signup using SAML.
+Configure a team for users to join automatically
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. warning::
+After you have enabled SAML on your organization,
+a team named "SAML Users" will be created automatically,
+and all users that sign up with SAML will be automatically joined to this team.
+You can delete this team, or configure a different team or teams for users to join automatically.
 
-   Existing users with email addresses from your configured domain will not be required to sign up using SAML,
-   but they won't be automatically joined to your organization.
-
-Configure team for all users to join
-------------------------------------
-
-You can mark one or more teams that users will automatically join when they sign up with a matching email address.
-Configure this option by:
+To configure a team for users to join automatically:
 
 1. Navigate to the `teams management page <https://readthedocs.com/organizations/choose/organization_team_list/>`__.
 2. Click the :guilabel:`<team name>`.
 3. Click :guilabel:`Edit team`
 4. Enable *Auto join users with an organization's email address to this team*.
 5. Click :guilabel:`Save`
 
-With this enabled,
-all users that sign up with SAML will automatically join this team.
-These teams can have either *read-only* or *admin* permissions over a set of projects.
+User management
+---------------
+
+New users
+~~~~~~~~~
+
+After enabling the SAML integration,
+all users with an email domain matching the one in your SAML integration will be required to sign up using SAML.
+After they sign up, they will be automatically joined to your organization within the teams you have configured to auto-join users.
+
+Existing users
+~~~~~~~~~~~~~~
+
+Existing users with email addresses from your configured domain will not be required to sign in using SAML,
+but they won't be automatically joined to your organization.
+
+If you want to enforce SAML for existing users, you have the following options:
+
+- Users can delete their accounts, and sign up again using SAML.
+- Users can link their existing accounts to their SAML identity by following this link while logged in their Read the Docs account:
+  ``https://readthedocs.com/accounts/saml/<organization-slug>/login/?process=connect`` (replace ``<organization-slug>`` with your organization slug).
+  You can find this link in your `organization's SAML settings page <https://readthedocs.com/organizations/choose/organization_saml/>`__.
+
+Outside collaborators
+~~~~~~~~~~~~~~~~~~~~~
+
+You can still add outside collaborators that don't use SAML and manage their access.
+There are two ways to manage this access:
+
+* Using :doc:`teams </guides/manage-read-the-docs-teams>` to provide access for ongoing contribution.
+* Using :doc:`sharing </commercial/sharing>` to provide short-term access requiring a login.
 
 Revoke user's access to all the projects
-----------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 By disabling access to the SAML integration to a user,
-you revoke access to all the projects the linked Read the Docs user had access to,
+you revoke access to all the projects their linked Read the Docs user had access to,
 and disable login on Read the Docs completely for that user.
 
 .. warning::

docs/user/guides/set-up-single-sign-on-saml.rst

@@ -1,5 +1,5 @@
-``sitemap.xml`` support
-=======================
+Sitemap support
+===============
 
 `Sitemaps <https://www.sitemaps.org/>`__ allow you to inform search engines about URLs that are available for crawling.
 This makes your content more :term:`discoverable <discoverability>`,
@@ -17,10 +17,8 @@ It contains information such as:
 * What translations are available for a page.
 
 Read the Docs automatically generates a ``sitemap.xml`` for your project,
-
-By default the sitemap includes:
-
-* Each version of your documentation and when it was last updated, sorted by version number.
+by default the sitemap includes each version of your documentation and when it was last updated,
+sorted by version number.
 
 This allows search engines to prioritize results based on the version number,
 sorted by `semantic versioning`_.

docs/user/reference/sitemaps.rst

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

package.json

@@ -1,4 +1,4 @@
 """Read the Docs."""
 
 
-__version__ = "11.7.1"
+__version__ = "11.7.2"

readthedocs/__init__.py

@@ -93,6 +93,8 @@ class ErrorView(TemplateView):
     multiple subpaths for errors, as we need to show application themed errors
     for dashboard users and minimal error pages for documentation readers.
 
+    Template resolution also uses fallback to generic 4xx/5xx error templates.
+
     View arguments:
 
     status_code
@@ -105,49 +107,38 @@ class ErrorView(TemplateView):
         separate path from Proxito error templates.
     """
 
-    base_path = "errors/dashboard/"
-    status_code = 500
+    base_path = "errors/dashboard"
+    status_code = None
+    template_name = None
 
     def get_status_code(self):
-        status_code = self.status_code
-        try:
-            status_code = int(self.kwargs["status_code"])
-        except (ValueError, KeyError):
-            pass
-        return status_code
+        return self.kwargs.get("status_code", self.status_code)
+
+    def get_template_name(self):
+        return self.kwargs.get("template_name", self.template_name)
 
     def get_template_names(self):
-        status_code = self.get_status_code()
-        if settings.RTD_EXT_THEME_ENABLED:
-            # First try to load the template for the specific HTTP status code
-            # and fall back to a generic 400/500 level error template
-            status_code_class = int(status_code / 100)
-            generic_code = f"{status_code_class}xx"
-            return [
-                f"{self.base_path}/{code}.html" for code in [status_code, generic_code]
-            ]
-        # TODO the legacy dashboard has top level path errors, as is the
-        # default. This can be removed later.
-        return f"{status_code}.html"
+        template_names = []
+        if (template_name := self.get_template_name()) is not None:
+            template_names.append(template_name.rstrip("/"))
+        if (status_code := self.get_status_code()) is not None:
+            template_names.append(str(status_code))
+        return [f"{self.base_path}/{file}.html" for file in template_names]
+
+    def get_context_data(self, **kwargs):
+        context_data = super().get_context_data(**kwargs)
+        context_data["status_code"] = self.get_status_code()
+        return context_data
 
     def dispatch(self, request, *args, **kwargs):
-        context = self.get_context_data(**kwargs)
+        context = self.get_context_data()
         status_code = self.get_status_code()
         return self.render_to_response(
             context,
             status=status_code,
         )
 
 
-# TODO replace this with ErrorView and a template in `errors/` instead
-class TeapotView(TemplateView):
-    template_name = "core/teapot.html"
-
-    def get(self, request, *args, **kwargs):
-        context = self.get_context_data(**kwargs)
-        return self.render_to_response(context, status=418)
-
-
 class PageNotFoundView(View):
 
     """Just a 404 view that ignores all URL parameters."""