Large docs refactor (#11641)

* Large docs refactor This was done on the plane, and hopefully doesn't conflict too much with my other docs PRs. The big work here is: * Combining the Git integration & Automatic git integration pages. They were never properly seperated * Making the Continuous Doc Deployment page ready to be shown * Decent updates to the Versions page * Lots of small updates * A couple small cleanup bits * A couple more small bits * Fix references * Link to ref page on the add project page * Update docs/user/guides/importing-private-repositories.rst Co-authored-by: Sam <[email protected]> * Clarify search results --------- Co-authored-by: Sam <[email protected]>
readthedocs · Oct 7, 2024 · 630af65 · 630af65
1 parent e366e7f
commit 630af65
Show file tree

Hide file tree

Showing 20 changed files with 354 additions and 430 deletions.
diff --git a/docs/user/builds.rst b/docs/user/builds.rst
@@ -1,7 +1,7 @@
 Build process overview
 ======================
 
-Once a project has been imported and a build is triggered,
+Once a project has been added and a build is triggered,
 Read the Docs executes a set of :term:`pre-defined jobs <pre-defined build jobs>` to build and upload documentation.
 This page explains in detail what happens behind the scenes,
 and includes an overview of how you can change this process.
@@ -17,12 +17,11 @@ It also gives you the knowledge to customize the build process.
    All the steps are run inside a Docker container, using the image defined in :ref:`config-file/v2:build.os`.
    The build has access to all :doc:`pre-defined environment variables </reference/environment-variables>` and :doc:`custom environment variables </environment-variables>`.
 
-
 The build process includes the following jobs:
 
 :checkout:
 
-   Checks out a project's code from the repository URL.
+   Checks out a project's code from the Git repository.
    On |com_brand|,
    this environment includes the SSH deploy key that gives access to the repository.
 
@@ -38,11 +37,11 @@ The build process includes the following jobs:
 
    Creates a Python environment to install all the dependencies in an isolated and reproducible way.
    Depending on what's defined by the project,
-   a virtualenv or a conda environment (:ref:`config-file/v2:conda`) will be used.
+   a :term:`virtualenv` or a :ref:`conda environment <config-file/v2:conda>` will be used.
 
 :install:
 
-   Install :doc:`default and project dependencies </build-default-versions>`.
+   Installs :doc:`default and project dependencies </build-default-versions>`.
    This includes any requirements you have configured in :ref:`config-file/v2:requirements file`.
 
    If the project has extra Python requirements,
@@ -60,10 +59,9 @@ The build process includes the following jobs:
 :upload:
 
    Once the build process finishes successfully,
-   the resulting artifacts are uploaded to our servers.
+   the resulting artifacts (HTML, PDF, etc.) are uploaded to our servers.
    Our :doc:`CDN </reference/cdn>` is then purged so your docs are *always up to date*.
 
-
 .. seealso::
 
     If you require additional build steps or customization,
@@ -85,8 +83,7 @@ Read the Docs supports three different mechanisms to cancel a running build:
 
 :Manually:
 
-   Once a build was triggered,
-   project administrators can go to the build detail page
+   Project administrators can go to the build detail page
    and click :guilabel:`Cancel build`.
 
 :Automatically:
@@ -100,29 +97,25 @@ Read the Docs supports three different mechanisms to cancel a running build:
    to check for your own cancellation condition and then return exit code ``183`` to cancel a build.
    You can exit with the code ``0`` to continue running the build.
 
-   When this happens, Read the Docs will notify your Git platform (GitHub/GitLab) that the build succeeded (✅),
+   When this happens, Read the Docs will notify your :doc:`Git provider </reference/git-integration>` the build succeeded (✅),
    so the pull request doesn't have any failing checks.
 
    .. tip::
 
       Take a look at :ref:`build-customization:cancel build based on a condition` section for some examples.
 
-
 Build resources
 ---------------
 
 Every build has limited resources assigned to it.
-Generally, |com_brand| users get double the build resources,
-with the option to increase that.
-
 Our build limits are:
 
 .. tabs::
 
    .. tab:: |com_brand|
 
       * 30 minutes build time
-      * 7GB of memory
+      * 7GB of memory (upgradable)
       * Concurrent builds vary based on your pricing plan
 
       If you are having trouble with your documentation builds,
@@ -134,9 +127,9 @@ Our build limits are:
       * 7GB of memory
       * 2 concurrent builds
 
-      We can increase build limits on a per-project basis.
+      We can increase build length on a per-project basis.
       Send an email to [email protected] providing a good reason why your documentation needs more resources.
 
       If your business is hitting build limits hosting documentation on Read the Docs,
       please consider :doc:`Read the Docs for Business </commercial/index>`
-      which has much higher build resources.
+      which has options for additional build resources.
diff --git a/docs/user/config-file/index.rst b/docs/user/config-file/index.rst
@@ -1,28 +1,20 @@
 Configuration file overview
 ===========================
 
-As part of the initial set up for your Read the Docs site,
+As part of the initial set up of a Read the Docs project,
 you need to create a **configuration file** called ``.readthedocs.yaml``.
 The configuration file tells Read the Docs what specific settings to use for your project.
 
 This tutorial covers:
 
-#. Where to put your configuration file.
-#. What to put in the configuration file.
-#. How to customize the configuration for your project.
-
-.. seealso::
-
-   :doc:`/tutorial/index`.
-     Following the steps in our tutorial will help you setup your first documentation project.
-
+.. contents::
+    :local:
+    :depth: 1
 
 Where to put your configuration file
 ------------------------------------
 
 The ``.readthedocs.yaml`` file should be placed in the top-most directory of your project's repository.
-We will get to the contents of the file in the next steps.
-
 When you have changed the configuration file,
 you need to commit and push the changes to your Git repository.
 Read the Docs will then automatically find and use the configuration to build your project.
@@ -43,7 +35,8 @@ Getting started with a template
 
 Here are some configuration file examples to help you get started.
 Pick an example based on the tool that your project is using,
-copy its contents to ``.readthedocs.yaml`` and add the file to your Git repository.
+copy its contents to ``.readthedocs.yaml``,
+and add the file to your Git repository.
 
 .. tabs::
 
@@ -68,6 +61,8 @@ copy its contents to ``.readthedocs.yaml`` and add the file to your Git reposito
            :linenos:
            :caption: .readthedocs.yaml
 
+You can find more information about these tools in our :doc:`/intro/doctools`.
+
 Editing the template
 --------------------
 
@@ -88,6 +83,10 @@ Skip: file header and comments
 
 There are some parts of the templates that you can leave in place:
 
+``version`` key
+  The version key tells the system how to read the rest of the configuration file.
+  The current and only supported version is **version 2**.
+
 Comments
   We added comments that explain the configuration options and optional features.
   These lines begin with a ``#``.
@@ -97,11 +96,6 @@ Commented out features
   They are there as examples,
   which you can choose to enable, delete or save for later.
 
-``version`` key
-  The version key tells the system how to read the rest of the configuration file.
-  The current and only supported version is **version 2**.
-
-
 Adjust: ``build.os``
 ~~~~~~~~~~~~~~~~~~~~
 
@@ -118,7 +112,6 @@ or in the future when you need features from a newer Ubuntu.
    :ref:`config-file/v2:build.os`
      Configuration file reference with all values possible for ``build.os``.
 
-
 Adjust: Python configuration
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

diff --git a/docs/user/integrations.rst → docs/user/continuous-deployment.rst b/docs/user/integrations.rst → docs/user/continuous-deployment.rst
@@ -2,13 +2,6 @@
 
 :orphan:
 
-..
-   Some points we want to cover in this article:
-   * Talk about the benefits of always up to date docs
-   * Discuss versioning in here, since it relies directly on Git?
-   * Have a small diagram that shows (You --push--> GitHub --webhook--> RTD --Build docs--> Deploy
-       (Perhaps reuse this: https://about.readthedocs.com/images/homepage.png)
-
 Continuous Documentation Deployment
 ===================================
 
@@ -19,21 +12,20 @@ The Continuous Integration and Continuous Deployment (CI/CD) features are config
 such as GitHub, Bitbucket or GitLab.
 With each change committed to your repository, we are notified by the configured *webhook*.
 
-When we receive a *webhook* notification, we match it to a project's *Integration*.
-When a webhook is received, the matching project will then:
+When we receive a *webhook*, we match it to a project's *Integration*,
+and the following steps happen:
 
 * :doc:`Build </builds>` the latest commit.
-* Synchronize your versions based on the latest tag and branch data in Git.
+* Synchronize your :doc:`versions </versions>` based on the latest tag and branch data in Git.
 * Run your :doc:`automation rules</automation-rules>`.
 * Auto-cancel any currently running builds of the same version.
 * Add a log entry to the integration's :guilabel:`Recent Activity`.
 
-Continuous Documentation for software projects
-----------------------------------------------
+Documentation as code
+---------------------
 
 Documentation fits into any CI/CD pipeline by following a process known as *Documentation as Code (Docs as code)*.
-The primary method of doing this is by maintaining documentation alongside the source code,
-meaning that the documentation's life cycle is the same as your software project.
+This means that the documentation's life cycle is the same as your software project.
 By managing these changes in the same life cycle,
 you can benefit from **documentation and source code being part of the same code review process**.
 
@@ -43,24 +35,24 @@ This allows more iteration on documentation,
 and increases overall value from the documentation you write.
 
 As part of this quick feedback loop,
-You can preview documentation changes immediately using :doc:`pull request previews </pull-requests>`.
+you can preview documentation changes immediately using :doc:`pull request previews </pull-requests>`.
 
 Automated versioning
 --------------------
 
-With Read the Docs' automated CI/CD pipeline, you will be able to fully align your project's **release cycle** with your documentation.
+With Read the Docs you will be able to fully align your project's **release cycle** with your documentation.
 For instance, a new version of a software project can build and publish a :doc:`new documentation version </versions>`.
 
 When you release a new version for your project,
 you are likely also adding a version tag to your Git repository.
 These Git events can be configured to build and publish your documentation automatically with :doc:`/automation-rules`.
-If you use a versioning schema, you can configure it as part of the automation process.
+If you use a versioning scheme, you can configure it as part of the automation process.
 
 Whether you choose to handle versioning automatically or with manual control is up to you.
 
 Read the Docs will store your version history and make it possible for users to visit archived versions of your documentation.
-Your version setup is ultimately captured by the :term:`flyout menu`.
-
+Your version setup is ultimately captured by the :term:`flyout menu`,
+and can be integrated in your documentation with :doc:`/addons`.
 
 .. seealso::
 

diff --git a/docs/user/explanation/index.rst b/docs/user/explanation/index.rst
@@ -5,7 +5,7 @@
 Explanation
 ===========
 
-⏩️ :doc:`/integrations`
+⏩️ :doc:`/continuous-deployment`
   A high-level introduction to *Continuous Documentation Deployment*.
 
 ⏩️ :doc:`/subprojects`

diff --git a/docs/user/flyout-menu.rst b/docs/user/flyout-menu.rst
@@ -48,7 +48,7 @@ The flyout menu provides access to the following bits of Read the Docs functiona
 * A :doc:`version switcher </versions>` that shows users all of the active, unhidden versions they have access to.
 * :doc:`Offline formats </downloadable-documentation>` for the current version, including HTML & PDF downloads that are enabled by the project.
 * Links to the Read the Docs dashboard for the project.
-* Links to your :doc:`VCS provider </integrations>` that allow the user to quickly find the exact file that the documentation was rendered from.
+* Links to your :doc:`Git provider </reference/git-integration>` that allow the user to quickly find the exact file that the documentation was rendered from.
 * A search bar that gives users access to our :doc:`/server-side-search/index` of the current version.
 
 .. figure:: /_static/images/flyout-open.png

diff --git a/docs/user/glossary.rst b/docs/user/glossary.rst
@@ -59,8 +59,6 @@ so that you have a reference for how we're using them.
 
       The *maintainer* role does not exist on |com_brand|, which instead provides :doc:`/commercial/organizations`.
 
-      Please see :ref:`guides/setup/git-repo-automatic:git provider integrations` for more information.
-
    pinning
       To *pin* a requirement means to explicitly specify which version should be used.
       *Pinning* software requirements is the most important technique to make a project :term:`reproducible`.
@@ -144,6 +142,9 @@ so that you have a reference for how we're using them.
    user-defined build jobs
       Commands defined by the user that Read the Docs will execute when performing the build process.
 
+   virtualenv
+      The default way for Python projects to create an isolated environment. This ensures that a :doc:`reproducible set of dependencies </guides/reproducible-builds>` are installed so that you project builds the same way each time.
+
    webhook
       A webhook is a special URL that can be called from another service,
       usually with a secret token.

diff --git a/docs/user/guides/best-practice/links.rst b/docs/user/guides/best-practice/links.rst
@@ -64,7 +64,7 @@ Good practice ✅
 * 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.
 * Keep development versions :ref:`hidden <versions:Version states>` so people do not find them on search engines by mistake.
   This is the best way to ensure that nobody links to URLs that are intended for development purposes.
-* Use a :ref:`version warning <versions:Version warning>` to ensure the reader is aware in case they are reading an old (archived) version.
+* Use a :ref:`version warning notifications <versions:Version warning notifications>` to ensure the reader is aware in case they are reading an old (archived) version.
 
 .. tip::
 

diff --git a/docs/user/guides/build-troubleshooting.rst b/docs/user/guides/build-troubleshooting.rst
@@ -53,7 +53,7 @@ Permission denied (publickey)
 
 1. Navigate to :guilabel:`Admin > SSH Keys`
 2. Copy the contents of the public key.
-3. Ensure that the key exists as a deploy key at your VCS provider. Here are direct links to access settings for verifying and changing deploy keys - customize the URLs for your VCS host and repository details:
+3. Ensure that the key exists as a deploy key at your Git provider. Here are direct links to access settings for verifying and changing deploy keys - customize the URLs for your Git provider and repository details:
 
    - ``https://github.com/<username>/<repo>/settings/keys``
    - ``https://gitlab.com/<username>/<repo>/-/settings/repository``
@@ -72,7 +72,7 @@ ERROR: Repository not found.
 
 1. Navigate to :guilabel:`Admin > SSH Keys`
 2. Copy the contents of the public key.
-3. Ensure that the key exists as a deploy key at your VCS provider. Here are direct links to access settings for verifying and changing deploy keys - customize the URLs for your VCS host and repository details:
+3. Ensure that the key exists as a deploy key at your Git provider. Here are direct links to access settings for verifying and changing deploy keys - customize the URLs for your VCS host and repository details:
 
    - ``https://github.com/<username>/<repo>/settings/keys``
    - ``https://gitlab.com/<username>/<repo>/-/settings/repository``

diff --git a/docs/user/guides/connecting-git-account.rst b/docs/user/guides/connecting-git-account.rst
@@ -2,9 +2,9 @@ How to connect your Read the Docs account to your Git provider
 ==============================================================
 
 In this how to article,
-you are shown the steps to connect an account on |git_providers_or| with your Read the Docs account.
+we cover how to connect an account on |git_providers_or| with your Read the Docs account.
 This is relevant if you have signed up for Read the Docs with your email
-or if you have signed up using a Git provider account and want to connect additional providers.
+or want to connect additional providers.
 
 If you are going to import repositories from |git_providers_or|,
 you should connect your Read the Docs account to your Git provider first.
@@ -15,7 +15,6 @@ you should connect your Read the Docs account to your Git provider first.
    you're all done. Your account is connected ✅️.
    You only need this how-to if you want to connect additional Git providers.
 
-
 Adding a connection
 -------------------
 
@@ -47,7 +46,7 @@ Now your connection is ready and you will be able to import and configure Git re
 
 .. seealso::
 
-   :doc:`/guides/setup/git-repo-automatic`
+   :doc:`/reference/git-integration`
      Learn how the connected account is used for automatically configuring Git repositories and Read the Docs projects
      and which **permissions** that are required from your Git provider.
 

diff --git a/docs/user/guides/deprecating-content.rst b/docs/user/guides/deprecating-content.rst
@@ -39,7 +39,7 @@ and mark the :guilabel:`Hidden` option. Check :ref:`versions:Version States` for
 .. note::
 
    If the versions of your project follow the semver_ convention,
-   you can activate the :ref:`versions:version warning` option for your project.
+   you can activate the :ref:`versions:version warning notifications` option for your project.
    A banner with a warning and linking to the stable version
    will be shown on all versions that are lower than the stable one.
 

diff --git a/docs/user/guides/importing-private-repositories.rst b/docs/user/guides/importing-private-repositories.rst
@@ -41,7 +41,7 @@ with the following exception:
 
 After importing your project the build will fail,
 because Read the Docs doesn't have access to clone your repository.
-To give access, you'll need to add your project's public SSH key to your VCS provider.
+To give Read the Docs access to your repository, add your project's public SSH key to your Git provider.
 
 Copy your project's public key
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~