Docs: Update "How to import private repositories" (Diátaxis)

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

@@ -1,39 +1,43 @@
 How to import private repositories
 ==================================
 
-.. warning::
-
-   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
-   https://readthedocs.com/dashboard/import instead of importing it manually.
+.. include:: /shared/admonition-rtd-business.rst
 
 You can grant access to private Git repositories using |com_brand|.
 Here is how you set it up.
 
-If you are using an unsupported integration, or don't want to connect your account,
-you'll need to do some **extra steps in order to have your project working**.
+✅️ 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>`.
+  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.
+
+  You can still use the below guide if you need to recreate SSH keys for a private repository.
+
+⬇️ Logging in with another provider or email?
+  For all other Git provider setups,
+  you will need to configure the Git repository manually.
+
+  Follow the steps below.
+
+
+Importing your project manually
+-------------------------------
 
-#. **Manually import your project using an SSH URL**
-#. **Allow access to your project using an SSH key**
-#. **Setup a webhook to build your documentation on every commit**
+Git repositories aren't automatically listed for setups that are not connected to |git_providers_or|.
 
-.. contents:: Table of contents
-   :local:
-   :backlinks: none
-   :depth: 3
+.. image:: /img/screenshot-com-manual-import.png
+   :scale: 50%
+   :align: right
+   :alt: A cropped screenshot showing the first step of a manual import on |com_brand|.
 
-Importing your project
-----------------------
+That is the reason why this guide is an extension of the :doc:`manual Git repository setup </guides/git-integrations>`,
+with the following exception:
 
 #. Go to https://readthedocs.com/dashboard/import/manual/
-#. Fill the :guilabel:`Repository URL` field with the SSH form of your repository's URL,
-   e.g ``[email protected]:readthedocs/readthedocs.org.git``
-#. Fill the other required fields
-#. Click :guilabel:`Next`
 
-Giving access to your project with an SSH key
----------------------------------------------
+#. In the :guilabel:`Repository URL` field, you need to provide the SSH version of your repository's URL.
+   It starts with ``git@...``, for example ``[email protected]:readthedocs/readthedocs.org.git``.
 
 After importing your project the build will fail,
 because Read the Docs doesn't have access to clone your repository.
@@ -42,10 +46,14 @@ To give access, you'll need to add your project's public SSH key to your VCS pro
 Copy your project's public key
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-You can find the public SSH key of your Read the Docs project by:
+Next step is to locate a public SSH key which Read the Docs has automatically generated:
 
-#. Going to the :guilabel:`Admin` tab of your project
-#. Click on :guilabel:`SSH Keys`
+.. image:: /img/screenshot-com-ssh-keys.png
+   :scale: 50%
+   :align: right
+   :alt: A screenshot of the SSH Keys admin page.
+
+#. Going to the :menuselection:`Admin --> SSH Keys` tab of your project.
 #. Click on the fingerprint of the SSH key (it looks like ``6d:ca:6d:ca:6d:ca:6d:ca``)
 #. Copy the text from the :guilabel:`Public key` section
 
@@ -56,73 +64,74 @@ You can find the public SSH key of your Read the Docs project by:
 Add the public key to your project
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-GitHub
-''''''
+Now that you have copied the public key generated by Read the Docs,
+you need to add it to your Git repository's settings.
+
+.. tabs::
+
+   .. tab:: GitHub
 
-For GitHub, you can use
-`deploy keys with read only access <https://docs.github.com/en/developers/overview/managing-deploy-keys#deploy-keys>`__.
+      For GitHub, you can use
+      `deploy keys with read only access <https://docs.github.com/en/developers/overview/managing-deploy-keys#deploy-keys>`__.
 
-#. Go to your project on GitHub
-#. Click on :guilabel:`Settings`
-#. Click on :guilabel:`Deploy Keys`
-#. Click on :guilabel:`Add deploy key`
-#. Put a descriptive title and paste the
-   :ref:`public SSH key from your Read the Docs project <guides/importing-private-repositories:copy your project's public key>`
-#. Click on :guilabel:`Add key`
+      #. Go to your project on GitHub
+      #. Click on :guilabel:`Settings`
+      #. Click on :guilabel:`Deploy Keys`
+      #. Click on :guilabel:`Add deploy key`
+      #. Put a descriptive title and paste the
+         :ref:`public SSH key from your Read the Docs project <guides/importing-private-repositories:copy your project's public key>`
+      #. Click on :guilabel:`Add key`
 
-GitLab
-''''''
+   .. tab:: GitLab
 
-For GitLab, you can use `deploy keys with read only access <https://docs.gitlab.com/ee/user/project/deploy_keys/index.html>`__.
+      For GitLab, you can use `deploy keys with read only access <https://docs.gitlab.com/ee/user/project/deploy_keys/index.html>`__.
 
-#. Go to your project on GitLab
-#. Click on :guilabel:`Settings`
-#. Click on :guilabel:`Repository`
-#. Expand the :guilabel:`Deploy Keys` section
-#. Put a descriptive title and paste the
-   :ref:`public SSH key from your Read the Docs project <guides/importing-private-repositories:copy your project's public key>`
-#. Click on :guilabel:`Add key`
+      #. Go to your project on GitLab
+      #. Click on :guilabel:`Settings`
+      #. Click on :guilabel:`Repository`
+      #. Expand the :guilabel:`Deploy Keys` section
+      #. Put a descriptive title and paste the
+         :ref:`public SSH key from your Read the Docs project <guides/importing-private-repositories:copy your project's public key>`
+      #. Click on :guilabel:`Add key`
 
-Bitbucket
-'''''''''
+   .. tab:: Bitbucket
 
-For Bitbucket, you can use `access keys with read only access <https://confluence.atlassian.com/bitbucket/access-keys-294486051.html>`__.
+      For Bitbucket, you can use `access keys with read only access <https://confluence.atlassian.com/bitbucket/access-keys-294486051.html>`__.
 
-#. Go your project on Bitbucket
-#. Click on :guilabel:`Repository Settings`
-#. Click on :guilabel:`Access keys`
-#. Click on :guilabel:`Add key`
-#. Put a descriptive label and paste the
-   :ref:`public SSH key from your Read the Docs project <guides/importing-private-repositories:copy your project's public key>`
-#. Click on :guilabel:`Add SSH key`
+      #. Go your project on Bitbucket
+      #. Click on :guilabel:`Repository Settings`
+      #. Click on :guilabel:`Access keys`
+      #. Click on :guilabel:`Add key`
+      #. Put a descriptive label and paste the
+         :ref:`public SSH key from your Read the Docs project <guides/importing-private-repositories:copy your project's public key>`
+      #. Click on :guilabel:`Add SSH key`
 
-Azure DevOps
-''''''''''''
+   .. tab:: Azure DevOps
 
-For Azure DevOps, you can use `SSH key authentication <https://docs.microsoft.com/en-us/azure/devops/repos/git/use-ssh-keys-to-authenticate?view=azure-devops>`__.
+      For Azure DevOps, you can use `SSH key authentication <https://docs.microsoft.com/en-us/azure/devops/repos/git/use-ssh-keys-to-authenticate?view=azure-devops>`__.
 
-#. Go your Azure DevOps page
-#. Click on :guilabel:`User settings`
-#. Click on :guilabel:`SSH public keys`
-#. Click on :guilabel:`New key`
-#. Put a descriptive name and paste the
-   :ref:`public SSH key from your Read the Docs project <guides/importing-private-repositories:copy your project's public key>`
-#. Click on :guilabel:`Add`
+      #. Go your Azure DevOps page
+      #. Click on :guilabel:`User settings`
+      #. Click on :guilabel:`SSH public keys`
+      #. Click on :guilabel:`New key`
+      #. Put a descriptive name and paste the
+         :ref:`public SSH key from your Read the Docs project <guides/importing-private-repositories:copy your project's public key>`
+      #. Click on :guilabel:`Add`
 
-Others
-''''''
+   .. tab:: Others
 
-If you are not using any of the above providers,
-Read the Docs will still generate a pair of SSH keys.
-You'll need to add the :ref:`public SSH key from your Read the Docs project <guides/importing-private-repositories:copy your project's public key>`
-to your repository.
-Refer to your provider's documentation for the steps required to do this.
+      If you are not using any of the above providers,
+      Read the Docs will still generate a pair of SSH keys.
+      You'll need to add the :ref:`public SSH key from your Read the Docs project <guides/importing-private-repositories:copy your project's public key>`
+      to your repository.
+      Refer to your provider's documentation for the steps required to do this.
 
 Webhooks
 --------
 
-To build your documentation on every commit,
-you'll need to manually add a webhook, see :doc:`/integrations`.
-If you are using an unsupported integration,
-you may need to setup a custom integration
-using our :ref:`generic webhook <webhook-integration-generic>`.
+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`.

docs/user/guides/private-submodules.rst

@@ -65,7 +65,7 @@ Read the Docs can clone all the repositories with the same key.
 
 .. seealso::
 
-   :ref:`Allow access to your Azure DevOps repository with an SSH key <guides/importing-private-repositories:azure devops>`.
+   :ref:`Allow access to your Azure DevOps repository with an SSH key <guides/importing-private-repositories:Add the public key to your project>`.
 
 Others
 ------
@@ -76,4 +76,4 @@ you only need to add it to each submodule repository.
 
 .. seealso::
 
-   :ref:`guides/importing-private-repositories:Giving access to your project with an SSH key`
+   :doc:`/guides/importing-private-repositories`

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

@@ -10,7 +10,7 @@ please read :doc:`/commercial/single-sign-on`
 Prerequisites
 -------------
 
-.. include:: /_includes/organization-permissions.rst
+.. include:: /shared/organization-permissions.rst
 
 User setup
 ~~~~~~~~~~

docs/user/guides/setup-single-sign-on-google-email.rst

@@ -10,7 +10,7 @@ please read :doc:`/commercial/single-sign-on`
 Prerequisites
 -------------
 
-.. include:: /_includes/organization-permissions.rst
+.. include:: /shared/organization-permissions.rst
 
 User setup
 ~~~~~~~~~~