Docs: Relabel and move explanation and how-tos around OAuth (Diátaxis)

docs/user/connected-accounts.rst

@@ -1,28 +1,72 @@
-Connecting Your VCS Account
-===========================
+Connecting your Git repository
+==============================
+
+In this article, we explain how connecting your Read the Docs account to one of the supported Git providers
+automatically configures your Git repository and your Read the Docs project.
+
+✅️ 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?
+  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`
+
+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 GitHub, Bitbucket, or GitLab,
-you should connect your Read the Docs account to your repository host first.
 Connecting your account allows for:
 
-* Easier importing of your repositories
-* Automatically configure your repository :doc:`/integrations`
+* 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
-* Log into Read the Docs with your GitHub, Bitbucket, or GitLab credentials
+* Logging into Read the Docs with your |git_providers_or| credentials.
+
+
+.. seealso::
+
+   :ref:`intro/import-guide:Manually import your docs`
+     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.
+
+
+.. tip::
+
+   A single Read the Docs account can connect to many different Git providers.
+   This allows you to have a single login for all your various identities.
+
 
-If you signed up or logged in to Read the Docs with your GitHub, Bitbucket, or GitLab
-credentials, you're all done. Your account is connected.
+How does the connection work?
+-----------------------------
+
+Read the Docs uses `OAuth`_ to connect to your account at |git_providers_or|,
+You are asked to grant permissions for Read the Docs to perform a number of actions on your behalf.
+
+At the same time, we use this process for authentication (login)
+since we trust that |git_providers_or| have verified your user account and email address.
+
+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 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
+
+.. note::
+
+  Access granted to Read the Docs can always be revoked.
+  This is a function offered by all Git providers.
 
-To connect a social account, go to your :guilabel:`<Username dropdown>` > :guilabel:`Settings` > :guilabel:`Connected Services`.
-From here, you'll be able to connect to your GitHub, Bitbucket or GitLab
-account. This process will ask you to authorize a connection to Read the Docs,
-that allows us to read information about and clone your repositories.
 
 
 Permissions for connected accounts
 ----------------------------------
 
-Read the Docs does not generally ask for write permission to your repositories' code
+Read the Docs does not generally ask for *write* permission to your repository code
 (with one exception detailed below)
 and since we only connect to public repositories we don't need special permissions to read them.
 However, we do need permissions for authorizing your account
@@ -31,39 +75,72 @@ and to setup :doc:`/integrations`
 which allow us to build your documentation on every change to your repository.
 
 
-GitHub
-~~~~~~
+.. tabs::
 
-Read the Docs requests the following permissions (more precisely, `OAuth scopes`_)
-when connecting your Read the Docs account to GitHub.
+   .. tab:: GitHub
 
-.. _OAuth scopes: https://developer.github.com/apps/building-oauth-apps/understanding-scopes-for-oauth-apps/
+      Read the Docs requests the following permissions (more precisely, `OAuth scopes`_)
+      when connecting your Read the Docs account to GitHub.
 
-Read access to your email address (``user:email``)
-    We ask for this so you can create a Read the Docs account and login with your GitHub credentials.
+      .. _OAuth scopes: https://developer.github.com/apps/building-oauth-apps/understanding-scopes-for-oauth-apps/
 
-Administering webhooks (``admin:repo_hook``)
-    We ask for this so we can create webhooks on your repositories when you import them into Read the Docs.
-    This allows us to build the docs when you push new commits.
+      Read access to your email address (``user:email``)
+          We ask for this so you can create a Read the Docs account and login with your GitHub credentials.
 
-Read access to your organizations (``read:org``)
-    We ask for this so we know which organizations you have access to.
-    This allows you to filter repositories by organization when importing repositories.
+      Administering webhooks (``admin:repo_hook``)
+          We ask for this so we can create webhooks on your repositories when you import them into Read the Docs.
+          This allows us to build the docs when you push new commits.
 
-Repository status (``repo:status``)
-    Repository statuses allow Read the Docs to report the status
-    (eg. passed, failed, pending) of pull requests to GitHub.
-    This is used for a feature currently in beta testing
-    that builds documentation on each pull request similar to a continuous integration service.
+      Read access to your organizations (``read:org``)
+          We ask for this so we know which organizations you have access to.
+          This allows you to filter repositories by organization when importing repositories.
 
-.. note::
+      Repository status (``repo:status``)
+          Repository statuses allow Read the Docs to report the status
+          (eg. passed, failed, pending) of pull requests to GitHub.
+          This is used for a feature currently in beta testing
+          that builds documentation on each pull request similar to a continuous integration service.
+
+      .. note::
+
+          :doc:`Read the Docs for Business </commercial/index>`
+          asks for one additional permission (``repo``) to allow access to private repositories
+          and to allow us to setup SSH keys to clone your private repositories.
+          Unfortunately, this is the permission for read/write control of the repository
+          but there isn't a more granular permission
+          that only allows setting up SSH keys for read access.
+
+   .. tab:: Bitbucket
+
+      We request permissions for:
+
+      Administering your repositories (``repository:admin``)
+        We ask for this so we can create webhooks on your repositories when you import them into Read the Docs.
+        This allows us to build the docs when you push new commits.
+        NB! This permission scope does **not** include any write access to code.
+
+      Reading your account information including your email address
+        We ask for this so you can create a Read the Docs account and login with your Bitbucket credentials.
+
+      Read access to your team memberships
+        We ask for this so we know which organizations you have access to.
+        This allows you to filter repositories by organization when importing repositories.
+
+      Read access to your repositories
+        We ask for this so we know which repositories you have access to.
+
+      To read more about Bitbucket permissions, see `official Bitbucket documentation on API scopes`_
+
+      .. _official Bitbucket documentation on API scopes: https://developer.atlassian.com/cloud/bitbucket/bitbucket-cloud-rest-api-scopes/
+
+
+   .. tab:: GitLab
+
+      Like the others, we request permissions for:
+
+      * Reading your account information (``read_user``)
+      * API access (``api``) which is needed to create webhooks in GitLab
 
-    :doc:`Read the Docs for Business </commercial/index>`
-    asks for one additional permission (``repo``) to allow access to private repositories
-    and to allow us to setup SSH keys to clone your private repositories.
-    Unfortunately, this is the permission for read/write control of the repository
-    but there isn't a more granular permission
-    that only allows setting up SSH keys for read access.
 
 .. _github-permission-troubleshooting:
 
@@ -97,21 +174,3 @@ depending on where the project you are trying to access has permissions from.
        .. seealso:: GitHub doc on `requesting access to your organization OAuth`_ for step-by-step instructions.
 
        .. _requesting access to your organization OAuth: https://docs.github.com/en/github/setting-up-and-managing-your-github-user-account/managing-your-membership-in-organizations/requesting-organization-approval-for-oauth-apps
-
-Bitbucket
-~~~~~~~~~
-
-For similar reasons to those above for GitHub, we request permissions for:
-
-* Reading your account information including your email address
-* Read access to your team memberships
-* Read access to your repositories
-* Read and write access to webhooks
-
-GitLab
-~~~~~~
-
-Like the others, we request permissions for:
-
-* Reading your account information (``read_user``)
-* API access (``api``) which is needed to create webhooks in GitLab

docs/user/guides/administrators.rst

@@ -13,6 +13,7 @@ have a look at our :doc:`/tutorial/index`.
    :maxdepth: 1
 
    Connect your git repository <git-integrations>
+   Connect your Read the Docs account to your Git repository <connecting-git-account>
    Manage Custom Domains <custom-domains>
    Enable Canonical URLs <canonical-urls>
    technical-docs-seo-guide

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

@@ -0,0 +1,70 @@
+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.
+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.
+
+If you are going to import repositories from |git_providers_or|,
+you should connect your Read the Docs account to your Git provider first.
+
+.. note::
+
+   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 ✅️.
+   You only need this how-to if you want to connect additional Git providers.
+
+
+Adding a connection
+-------------------
+
+To connect your Read the Docs account with a Git provider,
+go to the main login menu: :guilabel:`<Username dropdown>` > :guilabel:`Settings` > :guilabel:`Connected Services`.
+
+From here, you'll be able to connect to your |git_providers_or|
+account. This process will ask you to authorize an integration with Read the Docs.
+
+.. figure:: /img/oauth_github_dialog.png
+   :width: 300px
+   :align: center
+   :alt: Screenshot of example OAuth dialog on GitHub
+
+   An example of how your OAuth dialog on GitHub may look.
+
+After approving the request,
+you will be taken back to Read the Docs.
+You will now see the account appear in the list of connected services.
+
+.. figure:: /img/screenshot_connected_services.png
+   :width: 600px
+   :align: center
+   :alt: Screenshot of Read the Docs "Connected Services" page with multiple services connected
+
+   Connected Services [#f1]_ [#f2]_ shows the list of Git providers that
+
+Now your connection is ready and you will be able to import and configure Git repositories with just a few clicks.
+
+.. seealso::
+
+   :doc:`/connected-accounts`
+     Learn about what a connected account with your Git provider is used for
+     and the permissions required for connecting accounts.
+
+Removing a connection
+---------------------
+
+You may at any time delete the connection from Read the Docs.
+Delete the connection makes Read the Docs forget the immediate access,
+but you should also disable our OAuth Application from your Git provider.
+
+* On GitHub, navigate to `Authorized OAuth Apps`_.
+* On Bitbucket, navigate to `Application Authorizations`_.
+* On GitLab, navigat to `Applications`_
+
+.. _Authorized OAuth Apps: https://github.com/settings/applications
+.. _Application Authorizations: https://bitbucket.org/account/settings/app-authorizations/
+.. _Applications: https://gitlab.com/-/profile/applications
+
+.. [#f1] `Connected Services on readthedocs.org <https://readthedocs.org/accounts/social/connections/>`_
+.. [#f2] `Connected Services on readthedocs.com <https://readthedocs.com/accounts/social/connections/>`_

docs/user/index.rst

@@ -81,6 +81,7 @@ to help you create fantastic documentation for your project.
    /integrations
    /custom-domains
    /pull-requests
+   /connected-accounts
    /downloadable-documentation
    /subprojects
    /single_version
@@ -155,8 +156,6 @@ and some of the core features of Read the Docs.
    /server-side-search/index
    /security-log
 
-   /connected-accounts
-
    /builds
    /build-customization
    /build-troubleshooting

docs/user/intro/import-guide.rst

@@ -33,7 +33,8 @@ these properties, and then click **Next** to
 Manually import your docs
 -------------------------
 
-If you do not have a connected account, you will need to select **Import Manually**
+If you have not :doc:`connected a Git provider account </guides/connecting-git-account>`,
+you will need to select **Import Manually**
 and enter the information for your repository yourself. You will also need to
 manually configure the webhook for your repository as well. When importing your
 project, you will be asked for the repository URL, along with some other
@@ -53,6 +54,11 @@ project on Read the Docs. Go to your project's :guilabel:`Admin` > :guilabel:`In
 configure a new webhook, or see :ref:`our steps for webhook creation <integrations:Integration Creation>`
 for more information on this process.
 
+.. seealso::
+
+   :doc:`/guides/git-integrations`
+      Once you have imported your git project, use this guide to manually set up basic and additional integration.
+
 .. note::
     The ``Admin`` page can be found at ``https://readthedocs.org/dashboard/<project-slug>/edit/``.
     You can access all of the project settings from the admin page sidebar.