Docs: Relabel howto guides for Git repository configuration (Diátaxis) (

#10247)

* WIP: Relabel how-to guides to create a bit more clarity on Git repo guides

* Clarify headers and labels for Git repository guides

* Rename user/connected-accounts.rst -> user/guides/setup/git-repo-automatic.rst

* Rename user/guides/git-integrations.rst -> user/guides/setup/git-repo-manual.rst

* Tweak introduction to "How to automatically configure a Git repository"

* Use accurate reference

* Clarify seealso

* Fix additional references that were intended for connecting the account

* Add guide contents seem more appropriate

* Add "Others" tab so it's clear we also support other providers

* nice with these clarifications, thanks for review @ericholscher

* Update references that broke after merging main

docs/dev/install.rst

@@ -214,8 +214,8 @@ debugging currently.
 Configuring connected accounts
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-These are optional steps to setup the :doc:`connected accounts <rtd:connected-accounts>`
-(GitHub, GitLab, and Bitbucket) in your development environment.
+These are optional steps to setup the :doc:`connected accounts <rtd:guides/connecting-git-account>`
+(|git_providers_and|) in your development environment.
 This will allow you to login to your local development instance
 using your GitHub, Bitbucket, or GitLab credentials
 and this makes the process of importing repositories easier.

docs/user/glossary.rst

@@ -137,4 +137,4 @@ 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/git-integrations` and :doc:`/build-notifications`
+      See also: :doc:`/guides/setup/git-repo-manual` and :doc:`/build-notifications`

docs/user/guides/connecting-git-account.rst

@@ -47,9 +47,9 @@ Now your connection is ready and you will be able to import and configure Git re
 
 .. seealso::
 
-   :doc:`/connected-accounts`
-     Learn about what a connected account with your Git provider is used for
-     and the permissions required for connecting accounts.
+   :doc:`/guides/setup/git-repo-automatic`
+     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.
 
 Removing a connection
 ---------------------

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

@@ -31,7 +31,7 @@ Git repositories aren't automatically listed for setups that are not connected t
    :align: right
    :alt: A cropped screenshot showing the first step of a manual import on |com_brand|.
 
-That is the reason why this guide is an extension of the :doc:`manual Git repository setup </guides/git-integrations>`,
+That is the reason why this guide is an extension of the :doc:`manual Git repository setup </guides/setup/git-repo-manual>`,
 with the following exception:
 
 #. Go to https://readthedocs.com/dashboard/import/manual/
@@ -134,4 +134,4 @@ Finally, since this is a manual project import:
 **Don't forget to add the Read the Docs webhook!**
 
 To automatically trigger new builds on Read the Docs,
-you'll need to manually add a webhook, see :doc:`/guides/git-integrations`.
+you'll need to manually add a webhook, see :doc:`/guides/setup/git-repo-manual`.

docs/user/guides/pull-requests.rst

@@ -74,7 +74,7 @@ Build status is not being reported to your Git provider
    your account with your Git provider.
 
 .. seealso::
-   - :ref:`guides/git-integrations:Debugging webhooks`
+   - :ref:`guides/setup/git-repo-manual:Debugging webhooks`
    - :ref:`github-permission-troubleshooting`
 
 .. _OAuth App: https://github.com/settings/applications

docs/user/guides/setup-single-sign-on-github-gitlab-bitbucket.rst

@@ -16,7 +16,7 @@ User setup
 ~~~~~~~~~~
 
 Users in your organization must have their GitHub, Bitbucket, or GitLab
-:doc:`account connected </connected-accounts>`,
+:doc:`account connected </guides/connecting-git-account>`,
 otherwise they won't have access to any project on Read the Docs after performing this change.
 You can read more about `granting permissions on GitHub`_ in their documentation.
 

docs/user/connected-accounts.rst → docs/user/guides/setup/git-repo-automatic.rst

@@ -1,27 +1,56 @@
-How to connect your Git repository
-==================================
+How to automatically configure a Git repository
+===============================================
 
 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.
+makes Read the Docs able to automatically configure your imported Git repositories and your Read the Docs projects.
 
 ✅️ Signed up with your Git provider?
   If you signed up or logged in to Read the Docs with your |git_providers_or|
   credentials, you're all done. Your account is connected.
-  The permissions that are granted are :ref:`explained below <connected-accounts:Permissions for connected accounts>`.
-⬇️ Signed up with your email address?
+
+  The rest of this guide helps to understand how the automatic configuration works.
+
+⏩️️ Signed up with your email address?
   If you have signed up to Read the Docs with your email address,
   you can add the connection to the Git provider afterwards.
-  See: :doc:`/guides/connecting-git-account`
+  You can also add a connection to an additional Git provider this way.
+
+  Please follow :doc:`/guides/connecting-git-account` in this case.
+
+Automatic configuration
+-----------------------
+
+When your Read the Docs account is connected to |git_providers_or| and you import a Git repository,
+the integration will automatically be configured on the Read the Docs project and on your Git repository.
+
+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`).
+#. 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,
+   and creates an incoming webhook whereby Read the Docs is notified of all future changes to commits, branches and tags in the Git repository.
+#. Your project's incoming webhook is automatically added to your Git repository's settings using the account connection.
+#. Read the Docs also configures your project to use the Git provider's webhook via your account connection,
+   so your project is ready to enable :doc:`Pull Request builds </guides/pull-requests>`.
+
+After the import,
+you can continue to configure the project.
+All settings can be modified,
+including the ones that were automatically created.
+
+.. TODO: The following is for a feature reference.
 
-If you are going to import repositories from |git_providers_or|,
-we recommend that you connect your Read the Docs account to your Git provider.
+.. If you are going to import repositories from |git_providers_or|,
+.. we recommend that you connect your Read the Docs account to your Git provider.
 
-Connecting your account allows for:
+.. Connecting your account allows for:
 
-* Easy import of your repositories.
-* Automatic configuration of your repository :doc:`/integrations`.
-  which allow Read the Docs to build your docs on every change to your repository
-* Logging into Read the Docs with your |git_providers_or| credentials.
+.. * Easy import of your repositories.
+.. * Automatic configuration of your repository :doc:`/integrations`.
+..   which allow Read the Docs to build your docs on every change to your repository
+.. * Logging into Read the Docs with your |git_providers_or| credentials.
 
 
 .. seealso::
@@ -51,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 the repository that you select in the :doc:`project import </intro/import-guide>`.
 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/guides/git-integrations.rst → docs/user/guides/setup/git-repo-manual.rst

@@ -1,16 +1,16 @@
-How to manually connect your Git repository
-===========================================
+How to manually configure a Git repository
+==========================================
 
 In this guide,
-you will find the simple steps to manually integrating your Read the Docs project with all Git providers that supports our generic API.
+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|.
 
-.. note::
-
-   If your account is connected to the provider,
-   we'll try to setup the integration automatically.
-   If something fails, you can still setup the integration manually.
+.. seealso::
 
+   :doc:`/guides/setup/git-repo-automatic`
+     You are now reading the guide to configuring a Git repository manually.
+     If your Read the Docs account is :doc:`connected to the Git provider </guides/connecting-git-account>`,
+     we can setup the integration automatically.
 
 
 ..
@@ -32,6 +32,8 @@ This includes most Git providers, for example |git_providers_and|.
 Provider-specific instructions
 ------------------------------
 
+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.
 
 .. tabs::
 
@@ -110,6 +112,10 @@ Provider-specific instructions
 
       .. _issue #8364: https://github.com/readthedocs/readthedocs.org/issues/8364
 
+   .. tab:: Others
+
+      Other providers are supported through a generic webhook, see :ref:`webhook-integration-generic`.
+
 
 Additional integration
 ----------------------
@@ -125,6 +131,18 @@ As an example, the URL pattern looks like this: ``https://readthedocs.org/api/v2
 Use this URL when setting up a new integration with your provider ^^ these steps vary depending on the provider.
 
 
+.. warning::
+
+   Git repositories that are imported manually **do not** have the required setup to send back a **commit status**.
+   If you need this integration,
+   you have to :doc:`configure the repository automatically </guides/setup/git-repo-automatic>`.
+
+.. seealso::
+
+   :doc:`/guides/build-notifications`
+      Learn how to add custom build notifications.
+
+
 .. _webhook-integration-generic:
 
 Using the generic API integration

docs/user/guides/setup/index.rst

@@ -6,13 +6,13 @@ The following how-to guides help you solve common tasks and challenges in the se
 ⏩️ :doc:`Connecting your Read the Docs account to your Git provider </guides/connecting-git-account>`
     Steps to connect an account on |git_providers_or| with your Read the Docs account.
 
-⏩️ :doc:`Connecting your Git repository automatically </connected-accounts>`
+⏩️ :doc:`Configuring a Git repository automatically </guides/setup/git-repo-automatic>`
     Once your account is connected to your Git provider,
     adding and configuring a Git repository **automatically** is possible for |git_providers_and|.
 
-⏩️ :doc:`Connecting your Git repository manually </guides/git-integrations>`
+⏩️ :doc:`Configuring a Git repository manually </guides/setup/git-repo-manual>`
     If you are connecting a Git repository from another provider (for instance Gitea or Codeberg),
-    this guide tells you how to add and configure the Webhook **manually**.
+    this guide tells you how to add and configure the webhook **manually**.
 
 ⏩️ :doc:`Managing custom domains </guides/custom-domains>`
     Hosting your documentation using your own domain name, such as ``docs.example.com``.
@@ -43,8 +43,8 @@ The following how-to guides help you solve common tasks and challenges in the se
    :hidden:
 
    Connecting your Read the Docs account to your Git provider </guides/connecting-git-account>
-   Connecting your Git repository automatically </connected-accounts>
-   Connecting your Git repository manually </guides/git-integrations>
+   Configuring a Git repository automatically </guides/setup/git-repo-automatic>
+   Configuring a Git repository manually </guides/setup/git-repo-manual>
    Managing custom domains </guides/custom-domains>
    Managing subprojects </guides/subprojects>
    Hiding a version </guides/hiding-a-version>

docs/user/integrations.rst

@@ -62,7 +62,7 @@ Your version setup is ultimately captured by the :term:`flyout menu`.
 
 .. seealso::
 
-    :doc:`/guides/git-integrations`
+    :doc:`/guides/setup/git-repo-manual`
         Information on setting up your Git repository to make Read the Docs automatically build your documentation project.
     :doc:`/automation-rules`
         Information on setting up your Git repository to make Read the Docs automatically build your documentation project.

docs/user/intro/import-guide.rst

@@ -11,7 +11,7 @@ For private repositories, please use :doc:`Read the Docs for Business </commerci
 Automatically import your docs
 ------------------------------
 
-If you have :doc:`connected your Read the Docs account <../connected-accounts>` to GitHub, Bitbucket, or GitLab,
+If you have :doc:`connected your Read the Docs account </guides/connecting-git-account>` to GitHub, Bitbucket, or GitLab,
 you will see a list of your repositories that we are able to import.
 To import one of these projects, just click the import
 icon next to the repository you'd like to import. This will bring up a form that
@@ -55,7 +55,7 @@ configure a new webhook.
 
 .. seealso::
 
-   :doc:`/guides/git-integrations`
+   :doc:`/guides/setup/git-repo-manual`
       Once you have imported your git project, use this guide to manually set up basic and additional *webhook* integration.
 
 .. note::

docs/user/tutorial/index.rst

@@ -81,7 +81,7 @@ On the authorization page, click the green :guilabel:`Authorize readthedocs` but
    that ensure that the workflow is as smooth as possible,
    like installing :term:`webhooks <webhook>`.
    If you want to learn more,
-   check out :ref:`connected-accounts:permissions for connected accounts`.
+   check out :ref:`guides/setup/git-repo-automatic:permissions for connected accounts`.
 
 After that, you will be redirected to Read the Docs,
 where you will need to confirm your e-mail and username.