Merge tag '10.1.0' into relcorp

Author: humitos

CHANGELOG.rst

@@ -1,3 +1,27 @@
+Version 10.1.0
+--------------
+
+:Date: August 22, 2023
+
+* `@ecormany <https://github.com/ecormany>`__: docs: typo fix on "Custom and built-in redirects" page (`#10651 <https://github.com/readthedocs/readthedocs.org/pull/10651>`__)
+* `@humitos <https://github.com/humitos>`__: Celery: use django-celery-beat scheduler (`#10647 <https://github.com/readthedocs/readthedocs.org/pull/10647>`__)
+* `@humitos <https://github.com/humitos>`__: Build: drop websupport2 support from conf.py template (`#10646 <https://github.com/readthedocs/readthedocs.org/pull/10646>`__)
+* `@ericholscher <https://github.com/ericholscher>`__: Remove the celery email tasks until we can debug them. (`#10641 <https://github.com/readthedocs/readthedocs.org/pull/10641>`__)
+* `@humitos <https://github.com/humitos>`__: Development: disable cached Loader on `DEBUG=True` (`#10640 <https://github.com/readthedocs/readthedocs.org/pull/10640>`__)
+* `@humitos <https://github.com/humitos>`__: Docs: update tutorial with the latest required changes (`#10639 <https://github.com/readthedocs/readthedocs.org/pull/10639>`__)
+* `@humitos <https://github.com/humitos>`__: Build: do not set `sphinx_rtd_theme` theme automatically (`#10638 <https://github.com/readthedocs/readthedocs.org/pull/10638>`__)
+* `@humitos <https://github.com/humitos>`__: Build: update links to blog post (`#10636 <https://github.com/readthedocs/readthedocs.org/pull/10636>`__)
+* `@stsewd <https://github.com/stsewd>`__: Proxito: allow to generate proxied API URLs with a prefix (`#10634 <https://github.com/readthedocs/readthedocs.org/pull/10634>`__)
+* `@ericholscher <https://github.com/ericholscher>`__: Small wording cleanup on Integration howto (`#10632 <https://github.com/readthedocs/readthedocs.org/pull/10632>`__)
+* `@github-actions[bot] <https://github.com/github-actions[bot]>`__: Dependencies: all packages updated via pip-tools (`#10628 <https://github.com/readthedocs/readthedocs.org/pull/10628>`__)
+* `@humitos <https://github.com/humitos>`__: Black: run black over all the code base (`#10619 <https://github.com/readthedocs/readthedocs.org/pull/10619>`__)
+* `@humitos <https://github.com/humitos>`__: Revert "Contact projects with a build in the last 3 years" (`#10618 <https://github.com/readthedocs/readthedocs.org/pull/10618>`__)
+* `@humitos <https://github.com/humitos>`__: Settings: remove CSRF_COOKIE_MASKED (`#10608 <https://github.com/readthedocs/readthedocs.org/pull/10608>`__)
+* `@stsewd <https://github.com/stsewd>`__: Versions: keep type of version in sync with the project (`#10606 <https://github.com/readthedocs/readthedocs.org/pull/10606>`__)
+* `@humitos <https://github.com/humitos>`__: Import: remove extra/advanced step from project import wizard (`#10603 <https://github.com/readthedocs/readthedocs.org/pull/10603>`__)
+* `@benjaoming <https://github.com/benjaoming>`__: Docs: Methodology section (`#10417 <https://github.com/readthedocs/readthedocs.org/pull/10417>`__)
+* `@humitos <https://github.com/humitos>`__: VCS: remove unused methods and make new Git pattern the default (`#8968 <https://github.com/readthedocs/readthedocs.org/pull/8968>`__)
+
 Version 10.0.0
 --------------
 

docs/conf.py

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

docs/user/_static/images/tutorial/github-template.png

@@ -0,0 +1,50 @@
+How to structure your documentation
+===================================
+
+A documentation project's ultimate goal is to be read and understood by a reader.
+Readers need to be able to :term:`discover <discoverability>` the information that they need.
+Without an defined structure,
+readers either won't find information that they need or get frustrated on the way.
+
+One of the largest benefits of a good structure is that it removes questions that keep authors from writing documentation.
+Starting with a blank page is often the hardest part of documentation,
+so anything we can do to remove this problem is a win.
+
+Choosing a structure
+--------------------
+
+Good news!
+You don't have to invent all of the structure yourself,
+since a lot of experience-based work has been done to come up with a universal documentation structure.
+
+In order to avoid starting with a blank page,
+we recommend a simple process:
+
+* Choose a structure for your documentation. We recommend `Diátaxis <https://diataxis.fr/>`_ for this.
+* Find a :doc:`example project </examples>` or template to start from.
+* Start writing by filling in the structure.
+
+This process helps you get started quickly,
+and helps keep things consistent for the reader of your documentation.
+
+.. _diataxis:
+
+Diátaxis Methodology
+--------------------
+
+The documentation you're reading is written using the Diátaxis framework.
+It has four major parts as summarized by this image:
+
+.. image:: https://diataxis.fr/_images/diataxis.png
+
+We recommend that you read more about it in the `official Diátaxis documentation <https://diataxis.fr/>`_.
+
+Explaining the structure to your users
+--------------------------------------
+
+One of the benefits of Diátaxis is that it's a well-known structure,
+and users might already be familiar with it.
+As long as you stick to the structure,
+your users should be able to use existing experience to navigate.
+
+Using the names that are defined (eg. Tutorials, Explanation) in a user-facing way also helps here.

docs/user/explanation/documentation-structure.rst

@@ -0,0 +1,37 @@
+Methodology and best practice
+=============================
+
+In this section,
+we are covering important methods and best practices that will make your documentation better.
+
+.. seealso::
+
+    `Write the Docs: Topic Archive <https://www.writethedocs.org/topics/>`__
+        A collection of conference talks and articles,
+        indexed by topic (eg. ``Metrics and analytics`` or ``Information architecture``)
+
+You can familiarize yourself with these topics before or after writing documentation.
+We encourage that you read this at any time,
+as this content is applicable to many stages of the documentation process.
+
+⏩️ :doc:`The Diátaxis Methodology <documentation-structure>`
+    We introduce the Diátaxis methodology which is also used for the documentation you are now reading.
+
+⏩️ :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.
+
+
+.. toctree::
+   :maxdepth: 2
+   :hidden:
+
+   documentation-structure
+   /guides/best-practice/index

docs/user/explanation/methodology.rst

@@ -1,9 +1,9 @@
-How to manually configure a Git repository
-==========================================
+How to manually configure a Git repository integration
+======================================================
 
 In this guide,
-you will find the simple steps to manually integrating your Read the Docs project with all Git providers that support our generic API.
-This includes most Git providers, for example |git_providers_and|.
+you will find the steps to manually integrate your Read the Docs project with any Git provider,
+including |git_providers_and|.
 
 .. seealso::
 
@@ -12,7 +12,6 @@ This includes most Git providers, for example |git_providers_and|.
      If your Read the Docs account is :doc:`connected to the Git provider </guides/connecting-git-account>`,
      we can setup the integration automatically.
 
-
 ..
   The following references were supposed to go inside tabs, which is
   supported here:
@@ -29,11 +28,11 @@ This includes most Git providers, for example |git_providers_and|.
 .. _webhook-integration-bitbucket:
 .. _webhook-integration-gitlab:
 
-Provider-specific instructions
-------------------------------
+Manual integration setup
+------------------------
 
-You need to configure your Git provider to call a webhook on Read the Docs.
-This will make Read the Docs build your documentation when a new commit, branch or tag is pushed to your repository.
+You need to configure your Git provider integration to call a webhook that alerts Read the Docs of changes.
+Read the Docs will sync versions and build your documentation when your Git repository is updated.
 
 .. tabs::
 
@@ -128,8 +127,7 @@ After you have added the integration, you'll see a link to information about the
 
 As an example, the URL pattern looks like this: ``https://readthedocs.org/api/v2/webhook/<project-name>/<id>/*``.
 
-Use this URL when setting up a new integration with your provider ^^ these steps vary depending on the provider.
-
+Use this URL when setting up a new integration with your provider, as explained above.
 
 .. warning::
 

docs/user/guides/setup/git-repo-manual.rst

@@ -20,7 +20,12 @@ Read the Docs: documentation simplified
 
    /choosing-a-site
    /integrations
+   /downloadable-documentation
+   /environment-variables
+   /subprojects
+   /localization
    /explanation/advanced
+   /explanation/methodology
 
 .. toctree::
    :maxdepth: 2

docs/user/index.rst

@@ -38,6 +38,10 @@ which will generate a new repository on your personal account
 This is the repository you will import on Read the Docs,
 and it contains the following files:
 
+``.readthedocs.yaml``
+  Read the Docs configuration file.
+  Required to setup the documentation build process.
+
 ``README.rst``
   Basic description of the repository, you will leave it untouched.
 
@@ -147,15 +151,9 @@ Name
 Repository URL
   The URL that contains the sources. Leave the automatically filled value.
 
-Repository type
-  Version control system used, leave it as "Git".
-
 Default branch
   Name of the default branch of the project, leave it as ``main``.
 
-Edit advanced project options
-  Leave it unchecked, we will make some changes later.
-
 After hitting the :guilabel:`Next` button, you will be redirected to the :term:`project home`.
 You just created your first project on Read the Docs! |:tada:|
 
@@ -287,13 +285,7 @@ When you are satisfied, you can merge the pull request!
 Adding a configuration file
 ---------------------------
 
-As of September 2023,
-:doc:`you will need to add a configuration file to build your documentation <rtd-blog:migrate-configuration-v2>`.
-Until then,
-this example project will build without the configuration file,
-but we **strongly recommend** completing this section in order to add a configuration file.
-
-The Settings page of the :term:`project home` allows you
+The Admin tab of the :term:`project home` allows you
 to change some *global* configuration values of your project.
 In addition, you can further customize the building process
 using the ``.readthedocs.yaml`` :doc:`configuration file </config-file/v2>`.
@@ -316,23 +308,28 @@ In this section, we will show you some examples of what a configuration file sho
    Settings that apply to the entire project are controlled in the web dashboard,
    while settings that are version or build specific are better in the YAML file.
 
-Upgrading the Python version
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Changing the Python version
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 For example, to explicitly use Python 3.8 to build your project,
-navigate to your GitHub repository, click on the :guilabel:`Add file` button,
-and add a ``.readthedocs.yaml`` file with these contents to the root of your project:
+navigate to your GitHub repository, click on ``.readthedocs.yaml`` file and then in the pencil icon ✏️ to edit the file
+and change the Python version as follows:
 
 .. code-block:: yaml
    :caption: .readthedocs.yaml
+   :emphasize-lines: 6
 
    version: 2
 
    build:
-     os: "ubuntu-20.04"
+     os: "ubuntu-22.04"
      tools:
        python: "3.8"
 
+   python:
+     install:
+       - requirements: docs/requirements.txt
+
 The purpose of each key is:
 
 ``version``
@@ -345,9 +342,12 @@ The purpose of each key is:
 ``build.tools.python``
   Declares the Python version to be used.
 
+``python.install.requirements``
+  Specifies the Python dependencies to install required to build the documentation.
+
 After you commit these changes, go back to your project home,
 navigate to the "Builds" page, and open the new build that just started.
-You will notice that one of the lines contains ``python3.8``:
+You will notice that one of the lines contains ``python -mvirtualenv``:
 if you click on it, you will see the full output of the corresponding command,
 stating that it used Python 3.8.6 to create the virtual environment.
 
@@ -387,15 +387,19 @@ click on the |:pencil2:| icon, and add these contents:
 
 .. code-block:: yaml
    :caption: .readthedocs.yaml
-   :emphasize-lines: 8-9
+   :emphasize-lines: 12-13
 
    version: 2
 
    build:
-     os: "ubuntu-20.04"
+     os: "ubuntu-22.04"
      tools:
        python: "3.8"
 
+   python:
+     install:
+       - requirements: docs/requirements.txt
+
    sphinx:
      fail_on_warning: true
 
@@ -414,11 +418,12 @@ go back to editing ``.readthedocs.yaml`` on GitHub and modify it as follows:
 
 .. code-block:: yaml
    :caption: .readthedocs.yaml
-   :emphasize-lines: 2-4
+   :emphasize-lines: 4-6
 
    python:
-     # Install our python package before building the docs
      install:
+       - requirements: docs/requirements.txt
+       # Install our python package before building the docs
        - method: pip
          path: .
 
@@ -547,36 +552,40 @@ and a new build will be triggered for it.
    You can read more about :ref:`hidden versions <versions:hidden>`
    in our documentation.
 
-Show a warning for old versions
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.. "Show a warning for old versions" feature is not available anymore.
+   We should re-write this section once we have the notification addons rolled out.
 
-When your project matures, the number of versions might increase.
-Sometimes you will want to warn your readers
-when they are browsing an old or outdated version of your documentation.
 
-To showcase how to do that, let's create a ``2.0`` version of the code:
-navigate to your GitHub repository, click on the branch selector,
-type ``2.0.x``, and click on "Create branch: 2.0.x from 'main'".
-This will trigger two things:
+   Show a warning for old versions
+   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-- Since ``2.0.x`` is your newest branch, ``stable`` will switch to tracking it.
-- A new ``2.0.x`` version will be created on your Read the Docs project.
-- Since you already have an active ``stable`` version, ``2.0.x`` will be activated.
+   When your project matures, the number of versions might increase.
+   Sometimes you will want to warn your readers
+   when they are browsing an old or outdated version of your documentation.
 
-From this point, ``1.0.x`` version is no longer the most up to date one.
-To display a warning to your readers, go to the :guilabel:`⚙ Admin` menu of your project home,
-click on the :guilabel:`Advanced Settings` link on the left,
-enable the "Show version warning" checkbox, and click the :guilabel:`Save` button.
+   To showcase how to do that, let's create a ``2.0`` version of the code:
+   navigate to your GitHub repository, click on the branch selector,
+   type ``2.0.x``, and click on "Create branch: 2.0.x from 'main'".
+   This will trigger two things:
 
-If you now browse the ``1.0.x`` documentation, you will see a warning on top
-encouraging you to browse the latest version instead. Neat!
+   - Since ``2.0.x`` is your newest branch, ``stable`` will switch to tracking it.
+   - A new ``2.0.x`` version will be created on your Read the Docs project.
+   - Since you already have an active ``stable`` version, ``2.0.x`` will be activated.
 
-.. figure:: /_static/images/tutorial/old-version-warning.png
-   :width: 80%
-   :align: center
-   :alt: Warning for old versions
+   From this point, ``1.0.x`` version is no longer the most up to date one.
+   To display a warning to your readers, go to the :guilabel:`⚙ Admin` menu of your project home,
+   click on the :guilabel:`Advanced Settings` link on the left,
+   enable the "Show version warning" checkbox, and click the :guilabel:`Save` button.
+
+   If you now browse the ``1.0.x`` documentation, you will see a warning on top
+   encouraging you to browse the latest version instead. Neat!
+
+   .. figure:: /_static/images/tutorial/old-version-warning.png
+      :width: 80%
+      :align: center
+      :alt: Warning for old versions
 
-   Warning for old versions
+      Warning for old versions
 
 Getting insights from your projects
 -----------------------------------

docs/user/tutorial/index.rst

@@ -159,7 +159,7 @@ You would set the following configuration::
     From URL: /example.html
     To URL: /examples/intro.html
 
-**Page Redirects apply to all versions of you documentation.**
+**Page Redirects apply to all versions of your documentation.**
 Because of this,
 the ``/`` at the start of the ``From URL`` doesn't include the ``/$lang/$version`` prefix (e.g.
 ``/en/latest``), but just the version-specific part of the URL.