Merge tag '11.8.0' into rel

Author: humitos

CHANGELOG.rst

@@ -1,3 +1,29 @@
+Version 11.8.0
+--------------
+
+:Date: September 25, 2024
+
+* `@agjohnson <https://github.com/agjohnson>`__: Prefetch build and project on version list (`#11616 <https://github.com/readthedocs/readthedocs.org/pull/11616>`__)
+* `@ericholscher <https://github.com/ericholscher>`__: Add speed up indexes (`#11614 <https://github.com/readthedocs/readthedocs.org/pull/11614>`__)
+* `@agjohnson <https://github.com/agjohnson>`__: Add support for successful build prefetch (`#11613 <https://github.com/readthedocs/readthedocs.org/pull/11613>`__)
+* `@ericholscher <https://github.com/ericholscher>`__: Add date version index on build (`#11612 <https://github.com/readthedocs/readthedocs.org/pull/11612>`__)
+* `@humitos <https://github.com/humitos>`__: Use theme 3.0.0rc2 (version/language selector) (`#11611 <https://github.com/readthedocs/readthedocs.org/pull/11611>`__)
+* `@github-actions[bot] <https://github.com/github-actions[bot]>`__: Dependencies: all packages updated via pip-tools (`#11609 <https://github.com/readthedocs/readthedocs.org/pull/11609>`__)
+* `@agjohnson <https://github.com/agjohnson>`__: Make terminology and paths consistent for onboarding announcements (`#11608 <https://github.com/readthedocs/readthedocs.org/pull/11608>`__)
+* `@humitos <https://github.com/humitos>`__: Add project: check YAML file for specific branch (`#11607 <https://github.com/readthedocs/readthedocs.org/pull/11607>`__)
+* `@agjohnson <https://github.com/agjohnson>`__: Drop unnecessary CSP directives for gold view (`#11605 <https://github.com/readthedocs/readthedocs.org/pull/11605>`__)
+* `@pllim <https://github.com/pllim>`__: Fix minor typo in "Version states" (`#11603 <https://github.com/readthedocs/readthedocs.org/pull/11603>`__)
+* `@github-actions[bot] <https://github.com/github-actions[bot]>`__: Dependencies: all packages updated via pip-tools (`#11602 <https://github.com/readthedocs/readthedocs.org/pull/11602>`__)
+* `@dbaston <https://github.com/dbaston>`__: Docs: Handle long commit messages in [skip ci] example (`#11601 <https://github.com/readthedocs/readthedocs.org/pull/11601>`__)
+* `@ericholscher <https://github.com/ericholscher>`__: Add exit_code to build errors (`#11597 <https://github.com/readthedocs/readthedocs.org/pull/11597>`__)
+* `@agjohnson <https://github.com/agjohnson>`__: Conditionally disabled custom 404 pages on dev docs (`#11596 <https://github.com/readthedocs/readthedocs.org/pull/11596>`__)
+* `@humitos <https://github.com/humitos>`__: Release 11.7.2 (`#11595 <https://github.com/readthedocs/readthedocs.org/pull/11595>`__)
+* `@humitos <https://github.com/humitos>`__: Docs: simplify "Add project" page (`#11559 <https://github.com/readthedocs/readthedocs.org/pull/11559>`__)
+* `@humitos <https://github.com/humitos>`__: Docs: make translation section more generic (`#11549 <https://github.com/readthedocs/readthedocs.org/pull/11549>`__)
+* `@plaindocs <https://github.com/plaindocs>`__: Add list of supported tools (`#11547 <https://github.com/readthedocs/readthedocs.org/pull/11547>`__)
+* `@humitos <https://github.com/humitos>`__: Addons: prepare Proxito and dashboard to enable them by default (`#11513 <https://github.com/readthedocs/readthedocs.org/pull/11513>`__)
+* `@ericholscher <https://github.com/ericholscher>`__: Add success messages for Organization views (`#11480 <https://github.com/readthedocs/readthedocs.org/pull/11480>`__)
+
 Version 11.7.2
 --------------
 

common

@@ -21,7 +21,8 @@
     "hoverxref.extension",
     "multiproject",
     "myst_parser",
-    "notfound.extension",
+    # For testing, conditionally disable the custom 404 pages on dev docs
+    # "notfound.extension",
     "sphinx_copybutton",
     "sphinx_design",
     "sphinx_tabs.tabs",
@@ -55,6 +56,10 @@
 
 docset = get_project(multiproject_projects)
 
+# Disable custom 404 on dev docs
+if docset == "user":
+    extensions.append("notfound.extension")
+
 ogp_site_name = "Read the Docs Documentation"
 ogp_use_first_image = True  # https://github.com/readthedocs/blog/pull/118
 ogp_image = "https://docs.readthedocs.io/en/latest/_static/img/logo-opengraph.png"
@@ -76,7 +81,7 @@
 
 master_doc = "index"
 copyright = "Read the Docs, Inc & contributors"
-version = "11.7.2"
+version = "11.8.0"
 release = version
 exclude_patterns = ["_build", "shared", "_includes"]
 default_role = "obj"

docs/conf.py

@@ -183,7 +183,7 @@ This other example shows how to cancel a build if the commit message contains ``
        post_checkout:
          # Use `git log` to check if the latest commit contains "skip ci",
          # in that case exit the command with 183 to cancel the build
-         - (git --no-pager log --pretty="tformat:%s -- %b" -1 | grep -viq "skip ci") || exit 183
+         - (git --no-pager log --pretty="tformat:%s -- %b" -1 | paste -s -d " " | grep -viq "skip ci") || exit 183
 
 
 Generate documentation from annotated sources with Doxygen

docs/user/_static/images/first-steps/admin-panel.png

@@ -11,12 +11,21 @@ so that you have a reference for how we're using them.
       In some scenarios, they exist as two separate platforms.
       Read the Docs is a combined CI/CD platform made for documentation.
 
+   configuration file
+      YAML configuration file (e.g. ``.readthedocs.yaml``) that configures the build process of your project on Read the Docs.
+
+      .. seealso::
+
+         :doc:`/config-file/index`
+            Practical steps to add a configuration file to your documentation project.
+
+
    dashboard
       The "admin" site where Read the Docs projects are managed and configured.
       This varies for our two properties:
 
-       * |com_brand|: https://readthedocs.com/dashboard/.
-       * |org_brand|: https://readthedocs.org/dashboard/.
+       * |com_brand|: https://app.readthedocs.com/dashboard/
+       * |org_brand|: https://app.readthedocs.org/dashboard/
 
    default version
       Projects have a *default version*, usually the latest stable version of a project.
@@ -145,4 +154,10 @@ so that you have a reference for how we're using them.
       * Git providers have webhooks which are special URLs that Read the Docs can call in order to notify about documentation builds.
       * Read the Docs has a unique webhook for each project that the Git provider calls when changes happen in Git.
 
-      See also: :doc:`/guides/setup/git-repo-manual` and :doc:`/build-notifications`
+      .. seealso::
+
+         :doc:`/guides/setup/git-repo-manual`
+            Manually configuration for Git repositories.
+
+         :doc:`/build-notifications`
+            Receive notifications when your documentation builds fail.

docs/user/_static/images/first-steps/import-a-repository.png

@@ -8,7 +8,7 @@ Here is how you set it up.
 
 ✅️ Logged in with |git_providers_or|?
   If you signed up or logged in to Read the Docs with your |git_providers_or| credentials,
-  *all you have to do* is to use the normal :doc:`project import </intro/import-guide>`.
+  *all you have to do* is to use the normal :doc:`project import </intro/add-project>`.
   Your Read the Docs account is connected to your Git provider and
   will let you choose from private Git repositories and configure them for you.
 

docs/user/build-customization.rst

@@ -26,7 +26,7 @@ the integration will automatically be configured on the Read the Docs project an
 Here is an outline of what happens:
 
 #. A list of repositories that you have access to are automatically listed on Read the Docs' project import.
-#. You choose a Git repository from the list (see :doc:`/intro/import-guide`).
+#. You choose a Git repository from the list (see :doc:`/intro/add-project`).
 #. Data about the repository is now fetched using the account connection and you are asked to confirm the setup.
 #. When Read the Docs creates your project,
    it automatically sets up an integration with the Git provider,
@@ -55,7 +55,7 @@ including the ones that were automatically created.
 
 .. seealso::
 
-   :ref:`intro/import-guide:Manually import your docs`
+   :ref:`intro/add-project:Manually add your project`
      Using a different provider?
      Read the Docs still supports other providers such as Gitea or GitHub Enterprise.
      In fact, any Git repository URL can be configured manually.
@@ -80,7 +80,7 @@ By granting Read the Docs the requested permissions,
 we are issued a secret OAuth token from your Git provider.
 
 Using the secret token,
-we can automatically configure the repository that you select in the :doc:`project import </intro/import-guide>`.
+we can automatically configure repositories during :doc:`project creation </intro/add-project>`.
 We also use the token to send back build statuses and preview URLs for :doc:`pull requests </pull-requests>`.
 
 .. _OAuth: https://en.wikipedia.org/wiki/OAuth

docs/user/glossary.rst

@@ -36,10 +36,8 @@ A custom build configuration file path is applied to all versions of your docume
 Adding an additional project from the same repository
 -----------------------------------------------------
 
-Once you have added the first project from the :ref:`Import Wizard <intro/import-guide:Automatically import your docs>`,
-it will show as if it has already been imported and cannot be imported again.
-In order to add another project with the same repository,
-you will need to use the :ref:`Manual Import <intro/import-guide:Manually import your docs>`.
+Once you have added the first project from the :ref:`Import Wizard <intro/add-project:Automatically add your project>`,
+you will need to repeat this process again to add the additional project from the same repository.
 
 Setting the custom build configuration file
 -------------------------------------------

docs/user/guides/importing-private-repositories.rst

@@ -7,9 +7,10 @@ Read the Docs: documentation simplified
    :caption: Getting started
 
    /tutorial/index
-   /intro/getting-started-with-sphinx
-   /intro/getting-started-with-mkdocs
-   /intro/import-guide
+   /intro/doctools
+   /intro/mkdocs
+   /intro/sphinx
+   /intro/add-project
    /examples
 
 .. toctree::

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

@@ -0,0 +1,62 @@
+Adding a documentation project
+==============================
+
+.. meta::
+   :description lang=en: Add your existing documentation from a Git repository into Read the Docs.
+
+This page takes you through the process of adding a documentation project to Read the Docs.
+If you have :doc:`connected your Read the Docs account </guides/connecting-git-account>` to GitHub, Bitbucket or GitLab you will be able to add your project automatically.
+Otherwise, you will need to add it manually and perform some extra steps.
+
+Automatically add your project
+------------------------------
+
+#. Go to your :term:`dashboard`.
+#. Click on :guilabel:`Add project`.
+#. Type the name of the respository you want to add and click on it.
+#. Click on :guilabel:`Continue`.
+#. Edit any of the pre-filled fields with information of the repository.
+#. Click on :guilabel:`Next`.
+#. Add a :term:`configuration file` to your repository if it's doesn't exist yet.
+#. Click on :guilabel:`This file exists`.
+
+Manually add your project
+-------------------------
+
+#. Go to your :term:`dashboard`.
+#. Click on :guilabel:`Add project`.
+#. Click on :guilabel:`Configure manually`.
+#. Click on :guilabel:`Continue`.
+#. Fill all the fields of the form.
+#. Click on :guilabel:`Next`.
+#. Add a :term:`configuration file` to your repository if it's doesn't exist yet.
+#. Click on :guilabel:`This file exists`.
+
+Once your project is created, you'll need to manually configure the repository webhook if you would like to have new changes trigger builds for your project on Read the Docs.
+
+.. seealso::
+
+   :doc:`/guides/setup/git-repo-manual`
+      Additional setup steps required for manually created projects. This guide covers setting up SSH keys and webhook integrations.
+
+
+What's next
+-----------
+
+Once your documentation project is created, a build will be triggered.
+It will automatically fetch the code from your repository and build the documentation.
+You can see the logs for the build process from your :term:`dashboard`.
+
+.. seealso::
+
+   :doc:`/builds`
+      Explanation about the build process.
+
+   :doc:`/config-file/index`
+      Practical steps to add a configuration file to your documentation project.
+
+   :doc:`/versions`
+      Manage multiple versions of your documentation project.
+
+If you have any trouble, don't hesitate to reach out to us.
+The :doc:`support </support>` page has more information on getting in touch.

docs/user/guides/setup/monorepo.rst

@@ -0,0 +1,31 @@
+Supported tools
+===============
+
+Read the Docs provides hosting for static html documentation generated by Sphinx,
+MkDocs, Docusaurus and a variety of other tools.
+
+Here are minimal configuration examples for some common tools,
+with more coming soon.
+
+.. grid:: 2
+
+    .. grid-item-card::  Material for MkDocs
+        :link: mkdocs.html
+
+        Material for MkDocs is a powerful documentation framework on top of MkDocs.
+
+        Supported formats
+             :bdg-success:`md`
+        Written in
+             :bdg-info:`python`
+
+
+    .. grid-item-card::  Sphinx
+        :link: sphinx.html
+
+        Sphinx is a powerful documentation generator that has many features for writing technical documentation.
+
+        Supported formats
+             :bdg-success:`rst` :bdg-success:`md`
+        Written in
+             :bdg-info:`python`