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

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/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

@@ -5,7 +5,7 @@ How to import private repositories
 
    This guide is for users of :doc:`/commercial/index`.
    **If you are using GitHub, GitLab, or Bitbucket**,
-   we recommend :doc:`connecting your account </connected-accounts>` and importing your project from
+   we recommend :doc:`connecting your account </guides/connecting-git-account>` and importing your project from
    https://readthedocs.com/dashboard/import instead of importing it manually.
 
 You can grant access to private Git repositories using |com_brand|.

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,54 @@
-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 your Git Provider and you import a Git repository,
+all the basic settings 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 read using the account connection and you are asked to confirm the setup.
+#. Read the Docs creates the project with these basic settings,
+   including a unique webhook that the Git provider calls.
+#. Read the Docs uses the account connection to add its webhook URL on the Git repository's settings,
+   as well as adding an integration for :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 +78,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,11 +112,15 @@ 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
 ----------------------
 
-You can configure multiple webhooks.
+You can configure multiple incoming webhooks.
 
 To manually set up an integration, go to :guilabel:`Admin` > :guilabel:`Integrations` >  :guilabel:`Add integration`
 dashboard page and select the integration type you'd like to add.
@@ -125,6 +131,19 @@ 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::
+
+   :doc:`/guides/pull-requests`
+      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 webhooks.
    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.