Merge tag '9.9.1' into rel

Author: ericholscher

.readthedocs.yml

@@ -1,6 +1,8 @@
 version: 2
 
-formats: all
+formats:
+  - epub
+  - htmlzip
 
 sphinx:
   configuration: docs/conf.py

CHANGELOG.rst

@@ -1,3 +1,25 @@
+Version 9.9.1
+-------------
+
+:Date: March 21, 2023
+
+* `@humitos <https://github.com/humitos>`__: Build: use safe_open for security reasons (`#10165 <https://github.com/readthedocs/readthedocs.org/pull/10165>`__)
+* `@github-actions[bot] <https://github.com/github-actions[bot]>`__: Dependencies: all packages updated via pip-tools (`#10163 <https://github.com/readthedocs/readthedocs.org/pull/10163>`__)
+* `@agjohnson <https://github.com/agjohnson>`__: Update some docs for the new dashboard templates (`#10161 <https://github.com/readthedocs/readthedocs.org/pull/10161>`__)
+* `@ericholscher <https://github.com/ericholscher>`__: Revert 92a7182af42e26cab01265d2cc06fc7832832689 (`#10158 <https://github.com/readthedocs/readthedocs.org/pull/10158>`__)
+* `@humitos <https://github.com/humitos>`__: Lint: update common to get the latest linting changes (`#10154 <https://github.com/readthedocs/readthedocs.org/pull/10154>`__)
+* `@stsewd <https://github.com/stsewd>`__: Proxito: don't check for index.html if the path already ends with `/`. (`#10153 <https://github.com/readthedocs/readthedocs.org/pull/10153>`__)
+* `@ericholscher <https://github.com/ericholscher>`__: Docs: Disable PDF builds for now (`#10152 <https://github.com/readthedocs/readthedocs.org/pull/10152>`__)
+* `@stsewd <https://github.com/stsewd>`__: Put back template_name on proxito 404 view (`#10149 <https://github.com/readthedocs/readthedocs.org/pull/10149>`__)
+* `@silopolis <https://github.com/silopolis>`__: Fix doc_builder exceptions messages typos and spelling (`#10147 <https://github.com/readthedocs/readthedocs.org/pull/10147>`__)
+* `@humitos <https://github.com/humitos>`__: Release 9.9.0 (`#10146 <https://github.com/readthedocs/readthedocs.org/pull/10146>`__)
+* `@stsewd <https://github.com/stsewd>`__: Proxito: redirect http->https for public domains (`#10142 <https://github.com/readthedocs/readthedocs.org/pull/10142>`__)
+* `@benjaoming <https://github.com/benjaoming>`__: Removing non-used requirements file lint.in (`#10140 <https://github.com/readthedocs/readthedocs.org/pull/10140>`__)
+* `@humitos <https://github.com/humitos>`__: Build: pass `PATH` environment variable to Docker container (`#10133 <https://github.com/readthedocs/readthedocs.org/pull/10133>`__)
+* `@benjaoming <https://github.com/benjaoming>`__: Docs: New how-to sublevels (Diátaxis) (`#10131 <https://github.com/readthedocs/readthedocs.org/pull/10131>`__)
+* `@humitos <https://github.com/humitos>`__: Hosting: manual integrations via build contract (`#10127 <https://github.com/readthedocs/readthedocs.org/pull/10127>`__)
+* `@benjaoming <https://github.com/benjaoming>`__: Docs: emojis in TOC captions, FontAwesome on external links in TOC (Diátaxis) (`#10039 <https://github.com/readthedocs/readthedocs.org/pull/10039>`__)
+
 Version 9.9.0
 -------------
 

common

@@ -88,6 +88,17 @@ server {
         proxy_hide_header Content-Security-Policy;
         set $content_security_policy $upstream_http_content_security_policy;
         add_header Content-Security-Policy $content_security_policy always;
+
+        # This header allows us to decide whether or not inject the script at CloudFlare level
+        # Now, I'm injecting it in all the NGINX responses because `sub_filter` is not allowed inside an `if` statement.
+        set $rtd_hosting_integrations $upstream_http_x_rtd_hosting_integrations;
+        add_header X-RTD-Hosting-Integrations $rtd_hosting_integrations always;
+
+        # Inject our own script dynamically
+        # TODO: find a way to make this work _without_ running `npm run dev` from the `readthedocs-client` repository
+        sub_filter '</head>' '<script language="javascript" src="http://localhost:8000/readthedocs-client.js"></script>\n</head>';
+        sub_filter_last_modified on;
+        sub_filter_once on;
     }
 
     # Serve 404 pages here

dockerfiles/nginx/proxito.conf.template

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

docs/conf.py

@@ -6,10 +6,9 @@ Background
 
 .. note::
 
-    Consider this the canonical resource for contributing Javascript and CSS. We
-    are currently in the process of modernizing our front end development
-    procedures. You will see a lot of different styles around the code base for
-    front end JavaScript and CSS.
+   This information is for the current dashboard templates and JavaScript source
+   files and will soon be replaced by the new dashboard templates. This
+   information will soon be mostly out of date.
 
 Our modern front end development stack includes the following tools:
 

docs/dev/front-end.rst

@@ -98,6 +98,8 @@ save some work while typing docker compose commands. This section explains these
     * ``--no-reload`` makes all celery processes and django runserver
       to use no reload and do not watch for files changes
     * ``--ngrok`` is useful when it's required to access the local instance from outside (e.g. GitHub webhook)
+    * ``--ext-theme`` to use the new dashboard templates
+    * ``--webpack`` to start the Webpack dev server for the new dashboard templates
 
 ``inv docker.shell``
     Opens a shell in a container (web by default).

docs/dev/install.rst

@@ -187,9 +187,11 @@ This means that *both content and navigation path* for all sections should fit a
 Explanation
 ~~~~~~~~~~~
 
-* Introduce the scope: **“This article introduces ...”**
-  (write this as the very first thing,
-  then consider rewriting it or turning it into an internal comment afterwards).
+* Title convention: Use words indicating explanation in the title.
+  Like **Understanding <subject>**, **Dive into <subject>**, **Introduction to <subject>** etc.
+* Introduce the scope in the first paragraph: **“This article introduces ...”**.
+  Write this as the very first thing,
+  then re-read it and potentially shorten it later in your writing process.
 * Cross-reference the related How-to Guide.
   Put a ``seealso::`` somewhere visible.
   It should likely be placed right after the introduction,
@@ -200,9 +202,17 @@ Explanation
 How-to guides
 ~~~~~~~~~~~~~
 
-* Title should begin with **“How to ...”**,
-  but navigation titles should not contain the “How to” part.
+* Title should begin with **“How to ...”**.
+  If the how-to guide is specific for a tool, make sure to note it in the title.
+* Navigation titles should not contain the “How to” part.
+  Navigation title for "How to create a thing" is **Creating a thing**.
 * Introduce the scope: **“In this guide, we will…”**
+
+  * Introduction paragraph suggestions:
+
+    * "This guide shows <something>. <motivation>"
+    * "<motivation>. This guide shows you how."
+
 * Cross-reference related explanation.
   Put a ``seealso::`` somewhere visible,
   It should likely be placed right after the introduction
@@ -231,6 +241,7 @@ Tutorial
 
 .. note:: We don’t really have tutorials targeted in the systematic refactor, so this checklist isn’t very important right now.
 
+* "Getting started with <subject>" is likely a good start!
 * Cross-reference related explanation and how-to.
 * Try not to explain things too much, and instead link to the explanation content.
 * **Refactor other resources** so you can use references instead of disturbing the flow of the tutorial.

docs/dev/style-guide.rst

@@ -1,7 +1,7 @@
 How to connect your Git repository
 ==================================
 
-In this article, we explain how connecting your Read the Docs account to one of the supported Git providers
+In this article, we explain how connecting your Read the Docs account to |git_providers_or|
 automatically configures your Git repository and your Read the Docs project.
 
 ✅️ Signed up with your Git provider?

docs/user/connected-accounts.rst

@@ -0,0 +1,39 @@
+How-to guides: security and access
+==================================
+
+⏩️ :doc:`Single Sign-On (SSO) with GitHub, GitLab, or Bitbucket </guides/setup-single-sign-on-github-gitlab-bitbucket>`
+    When using an :doc:`organization </commercial/organizations>` on  |com_brand|,
+    you can configure SSO for your users to authenticate to Read the Docs.
+
+⏩️ :doc:`Single Sign-On (SSO) with Google Workspace </guides/setup-single-sign-on-google-email>`
+    When using an :doc:`organization </commercial/organizations>` on  |com_brand|,
+    you can configure SSO for your users to authenticate to Read the Docs.
+    This guide is written for Google Workspace.
+
+⏩️ :doc:`Managing Read the Docs teams </guides/manage-read-the-docs-teams>`
+    When using an :doc:`organization </commercial/organizations>` on  |com_brand|,
+    it's possible to create different teams with custom access levels.
+
+⏩️ :doc:`Manually importing private repositories </guides/importing-private-repositories>`
+    You can grant access to private Git repositories using |com_brand| using a custom process if required.
+    Here is how you set it up.
+
+⏩️ :doc:`Using private Git submodules </guides/private-submodules>`
+    If you are using private Git repositories and they also contain private Git submodules,
+    you need to follow a few special steps.
+
+⏩️ :doc:`Installing private python packages </guides/private-python-packages>`
+    If you have private dependencies, you can install them from
+    a :ref:`private Git repository <guides/private-python-packages:From a Git repository>` or
+    a :ref:`private repository manager <guides/private-python-packages:From a repository manager other than PyPI>`.
+
+.. toctree::
+   :maxdepth: 1
+   :hidden:
+
+   Single Sign-On (SSO) with GitHub, GitLab, or Bitbucket </guides/setup-single-sign-on-github-gitlab-bitbucket>
+   Single Sign-On (SSO) with Google Workspace </guides/setup-single-sign-on-google-email>
+   Managing Read the Docs teams </guides/manage-read-the-docs-teams>
+   Manually importing private repositories </guides/importing-private-repositories>
+   Using private Git submodules </guides/private-submodules>
+   Installing private python packages </guides/private-python-packages>

docs/user/guides/access/index.rst

@@ -0,0 +1,37 @@
+How-to guides: best practices
+=============================
+
+Over the years,
+we have become familiar with a number of methods that work well and which we consider **best practice**.
+
+⏩️ :doc:`Best practices for linking to your documentation </guides/best-practice/links>`
+    Documentation changes over time,
+    and links and cross-references can become challenging manage for various reasons.
+    Here is a set of best practices explaining and addressing these challenges.
+
+⏩️ :doc:`Deprecating content </guides/deprecating-content>`
+    Best practice for removing or deprecating documentation content.
+
+⏩️ :doc:`Creating reproducible builds </guides/reproducible-builds>`
+    Every documentation project has dependencies that are required to build it.
+    Using an unspecified versions of these dependencies means that your project can start breaking.
+    In this guide,
+    learn how to protect your project against breaking randomly.
+    **This is one of our most popular guides!**
+
+⏩️ :doc:`Search Engine Optimization (SEO) for documentation projects </guides/technical-docs-seo-guide>`
+    This article explains how documentation can be optimized to appear in search results,
+    increasing traffic to your docs.
+
+⏩️ :doc:`Hiding a version </guides/hiding-a-version>`
+    Learn how you can keep your entire version history online without overwhelming the reader with version choices.
+
+.. toctree::
+   :maxdepth: 1
+   :hidden:
+
+   Deprecating content </guides/deprecating-content>
+   Best practices for linking to your documentation </guides/best-practice/links>
+   Creating reproducible builds </guides/reproducible-builds>
+   Search Engine Optimization (SEO) for documentation projects </guides/technical-docs-seo-guide>
+   Hiding a version </guides/hiding-a-version>

docs/user/guides/administrators.rst

@@ -1,8 +1,9 @@
-How to troubleshoote build errors
-=================================
+Troubleshooting build errors
+============================
 
 .. include:: /shared/contribute-to-troubleshooting.rst
 
+This guide provides some common errors and resolutions encountered in the :doc:`build process </builds>`.
 
 Git errors
 ----------

docs/user/guides/authors.rst

@@ -1,9 +1,13 @@
 Troubleshooting slow builds
 ===========================
 
+This page contains a list of the most common issues that are slowing down builds.
+
 In case you are waiting a long time for your builds to finish
 or your builds are terminated by exceeding general resource limits,
 this troubleshooting guide will help you resolve some of the most common issues causing slow builds.
+Even if you are not facing any immediate performance issues,
+it's always good to be familiar with the most common ones.
 
 Build resources on Read the Docs are limited to make sure that users don't overwhelm our build systems.
 The current build limits can be found on our :ref:`Build resources reference <builds:Build resources>`.

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

@@ -0,0 +1,34 @@
+How-to guides: build process
+============================
+
+⏩️ :doc:`Setup build notifications and webhooks </guides/build-notifications>`
+    Build notifications can alert you when your builds fail so you can take immediate action.
+    In this guide,
+    you will learn how to get notified through various available channel integrations,
+    including email and chat.
+
+⏩️ :doc:`Configuring pull request builds </guides/pull-requests>`
+    Have your documentation built and access a preview for every :doc:`pull request builds </pull-requests>`.
+
+⏩️ :doc:`Using custom environment variables </guides/environment-variables>`
+    Extra environment variables, for instance secrets, may be needed in the build process and can be defined from the project's :term:`dashboard`.
+
+⏩️ :doc:`Managing versions automatically </guides/automation-rules>`
+    Automating your versioning on Read the Docs means you only have to handle your versioning logic in Git.
+    Learn how to define rules to automate creation of new versions on Read the Docs,
+    entirely using your Git repository's version logic.
+
+
+.. seealso:
+
+   :doc:`/builds`
+      An overview and introduction to the build process.
+
+.. toctree::
+   :maxdepth: 1
+   :hidden:
+
+   Setup build notifications and webhooks </guides/build-notifications>
+   Configuring pull request builds </guides/pull-requests>
+   Using custom environment variables </guides/environment-variables>
+   Managing versions automatically </guides/automation-rules>