Docs: Split and relabel VCS integration as explanation and how-to (Diátaxis) (#9675)

benjaoming · ericholscher · web-flow · commit a0080688ec60 · 2022-12-15T17:20:26.000+01:00
* Re-label VCS integration as a how-to guide and let's call it "Git platform integration"? * Revert back to saying VCS (to cut short discussion) * Revert another change, just to reduce distractions * WIP: Splitting up and updating VCS integration * Update references to integrations after the split * Remove the generic framing of VCS providers * Add git integrations to the list of explanations * Add a local table of content, move oddly placed instructions, fixup broken headline levels * Remove local TOC, move individual provider guides to tabs * Makes it possible to open up a tab using a sphinx label reference * Move Debugging Webhooks into Troubleshooting * Remove section Resyncing webhooks * Comment about scope * Update docs/user/integrations.rst Co-authored-by: Eric Holscher <25510+ericholscher@users.noreply.github.com> * WIP * Adds a draft of explanation of how continuous documentation fits into the landscape * Apply suggestions from code review @ericholscher Co-authored-by: Eric Holscher <25510+ericholscher@users.noreply.github.com> * Update docs/user/integrations.rst * Add explanation about versioning and a seealso for Automation Rules * Tweak the Automated Versioning subsection and add a seealso for the flyout menu * Refinements to versioning subsection * Update docs/user/integrations.rst Co-authored-by: Eric Holscher <25510+ericholscher@users.noreply.github.com> * Remove paragraph that already had a broken reference (even before AFAICT) and that does not lead to clear solutions * Make Git a proper noun. This way of writing "Git repository" etc. is widely used, example: https://git-scm.com/book/en/v2/Git-Basics-Getting-a-Git-Repository. Ref #9813 Co-authored-by: Eric Holscher <25510+ericholscher@users.noreply.github.com>
diff --git a/docs/_static/js/expand_tabs.js b/docs/_static/js/expand_tabs.js
@@ -1,9 +1,13 @@
 /*
  * Expands a specific tab of sphinx-tabs.
  * Usage:
- * - docs.readthedocs.io/?tab=Name
- * - docs.readthedocs.io/?tab=Name#section
- * Where 'Name' is the title of the tab (case sensitive).
+ * 1) docs.readthedocs.io/?tab=Name
+ * 2) docs.readthedocs.io/?tab=Name#section
+ * 3) docs.readthedocs.io/page#sphinx-label
+ * In 1) and 2), 'Name' is the title of the tab (case sensitive).
+ *
+ * In 3), you need to add a sphinx reference inside the tab.
+ * It mimics how sections are referenced and can be refactored.
 */
 $( document ).ready(function() {
   const urlParams = new URLSearchParams(window.location.search);
@@ -14,4 +18,20 @@ $( document ).ready(function() {
       tab.click();
     }
   }
+
+  // Uses a hash referencing a Sphinx label from the URL page#sphinx-label
+  var hash = window.location.hash.substr(1);
+  hash = hash.replace(/[^0-9a-z\-_]/gi, '');
+  // If the hash is inside a tab panel
+  var tab_with_reference = $(".sphinx-tabs-panel #" + hash).parents(".sphinx-tabs-panel");
+
+  if (tab_with_reference.length > 0) {
+    // Use the panel's ID to guess the tab's ID
+    var panel_id = tab_with_reference.first().attr("id");
+    var tab_id = panel_id.replace("panel-", "tab-");
+    // Invoke the tab buttons click() method to display it
+    $("button#" + tab_id).click();
+    // Scroll the tab widget into view
+    $('html, body').animate({ scrollTop: tab_with_reference.parents(".sphinx-tabs").first().offset().top}, 1000);
+  }
 });
diff --git a/docs/user/guides/administrators.rst b/docs/user/guides/administrators.rst
@@ -12,6 +12,7 @@ have a look at our :doc:`/tutorial/index`.
 .. toctree::
    :maxdepth: 1
 
+   Connect your git repository <git-integrations>
    Manage Custom Domains <custom-domains>
    Enable Canonical URLs <canonical-urls>
    technical-docs-seo-guide
diff --git a/docs/user/guides/git-integrations.rst b/docs/user/guides/git-integrations.rst
@@ -0,0 +1,204 @@
+How to manually connect your Git repository
+===========================================
+
+In this guide, you will find the simple steps to integrating your Read the Docs project with GitHub, Bitbucket, GitLab, Gitea or any other Git provider that supports our generic API.
+
+.. 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.
+
+
+Provider-specific instructions
+------------------------------
+
+.. tabs::
+
+   .. tab:: GitHub
+
+      .. _webhook-integration-github:
+
+      * Go to the :guilabel:`Settings` page for your **GitHub project**
+      * Click :guilabel:`Webhooks` > :guilabel:`Add webhook`
+      * For **Payload URL**, use the URL of the integration on your **Read the Docs project**,
+        found on the project's :guilabel:`Admin` > :guilabel:`Integrations` page.
+        You may need to prepend *https://* to the URL.
+      * For **Content type**, both *application/json* and
+        *application/x-www-form-urlencoded* work
+      * Leave the **Secrets** field blank
+      * Select **Let me select individual events**,
+        and mark **Branch or tag creation**, **Branch or tag deletion**, **Pull requests** and **Pushes** events
+      * Ensure **Active** is enabled; it is by default
+      * Finish by clicking **Add webhook**.  You may be prompted to enter your GitHub password to confirm your action.
+
+      You can verify if the webhook is working at the bottom of the GitHub page under **Recent Deliveries**.
+      If you see a Response 200, then the webhook is correctly configured.
+      For a 403 error, it's likely that the Payload URL is incorrect.
+
+      .. note:: The webhook token, intended for the GitHub **Secret** field, is not yet implemented.
+
+   .. tab:: Bitbucket
+
+      .. _webhook-integration-bitbucket:
+
+      * Go to the :guilabel:`Settings` > :guilabel:`Webhooks` > :guilabel:`Add webhook` page for your project
+      * For **URL**, use the URL of the integration on Read the Docs,
+        found on the :guilabel:`Admin` > :guilabel:`Integrations`  page
+      * Under **Triggers**, **Repository push** should be selected
+      * Finish by clicking **Save**
+
+   .. tab:: GitLab
+
+      .. _webhook-integration-gitlab:
+
+      * Go to the :guilabel:`Settings` > :guilabel:`Webhooks` page for your GitLab project
+      * For **URL**, use the URL of the integration on **Read the Docs project**,
+        found on the :guilabel:`Admin` > :guilabel:`Integrations`  page
+      * Leave the default **Push events** selected,
+        additionally mark **Tag push events** and **Merge request events**.
+      * Finish by clicking **Add Webhook**
+
+   .. tab:: Gitea
+
+      These instructions apply to any Gitea instance.
+
+      .. warning::
+
+         This isn't officially supported, but using the "GitHub webhook" is an effective workaround,
+         because Gitea uses the same payload as GitHub. The generic webhook is not compatible with Gitea.
+         See `issue #8364`_ for more details. Official support may be implemented in the future.
+
+      On Read the Docs:
+
+      * Manually create a "GitHub webhook" integration
+        (this will show a warning about the webhook not being correctly set up,
+        that will go away when the webhook is configured in Gitea)
+
+      On your Gitea instance:
+
+      * Go to the :guilabel:`Settings` > :guilabel:`Webhooks` page for your project on your Gitea instance
+      * Create a new webhook of type "Gitea"
+      * For **URL**, use the URL of the integration on Read the Docs,
+        found on the :guilabel:`Admin` > :guilabel:`Integrations` page
+      * Leave the default **HTTP Method** as POST
+      * For **Content type**, both *application/json* and
+        *application/x-www-form-urlencoded* work
+      * Leave the **Secret** field blank
+      * Select **Choose events**,
+        and mark **Branch or tag creation**, **Branch or tag deletion** and **Push** events
+      * Ensure **Active** is enabled; it is by default
+      * Finish by clicking **Add Webhook**
+      * Test the webhook with :guilabel:`Delivery test`
+
+      Finally, on Read the Docs, check that the warnings have disappeared
+      and the delivery test triggered a build.
+
+      .. _issue #8364: https://github.com/readthedocs/readthedocs.org/issues/8364
+
+
+Additional integration
+----------------------
+
+You can configure multiple 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.
+After you have added the integration, you'll see a link to information about the integration.
+
+As an example, the URL pattern looks like this: ``https://readthedocs.org/api/v2/webhook/<project-name>/<id>/*``.
+
+Use this URL when setting up a new integration with your provider ^^ these steps vary depending on the provider.
+
+
+.. _webhook-integration-generic:
+
+Using the generic API integration
+---------------------------------
+
+For repositories that are not hosted with a supported provider, we also offer a
+generic API endpoint for triggering project builds. Similar to webhook integrations,
+this integration has a specific URL, which can be found on the project's **Integrations** dashboard page
+(:guilabel:`Admin` > :guilabel:`Integrations`).
+
+Token authentication is required to use the generic endpoint, you will find this
+token on the integration details page. The token should be passed in as a
+request parameter, either as form data or as part of JSON data input.
+
+Parameters
+^^^^^^^^^^
+
+This endpoint accepts the following arguments during an HTTP POST:
+
+branches
+    The names of the branches to trigger builds for. This can either be an array
+    of branch name strings, or just a single branch name string.
+
+    Default: **latest**
+
+token
+    The integration token found on the project's **Integrations** dashboard page
+    (:guilabel:`Admin` > :guilabel:`Integrations`).
+
+For example, the cURL command to build the ``dev`` branch, using the token
+``1234``, would be::
+
+    curl -X POST -d "branches=dev" -d "token=1234" https://readthedocs.org/api/v2/webhook/example-project/1/
+
+A command like the one above could be called from a cron job or from a hook
+inside Git_, Subversion_, Mercurial_, or Bazaar_.
+
+.. _Git: http://www.kernel.org/pub/software/scm/git/docs/githooks.html
+.. _Subversion: https://www.mikewest.org/2006/06/subversion-post-commit-hooks-101
+.. _Mercurial: http://hgbook.red-bean.com/read/handling-repository-events-with-hooks.html
+.. _Bazaar: http://wiki.bazaar.canonical.com/BzrHooks
+
+Authentication
+^^^^^^^^^^^^^^
+
+This endpoint requires authentication. If authenticating with an integration
+token, a check will determine if the token is valid and matches the given
+project. If instead an authenticated user is used to make this request, a check
+will be performed to ensure the authenticated user is an owner of the project.
+
+Payload validation
+------------------
+
+If your project was imported through a connected account,
+we create a secret for every integration that offers a way to verify that a webhook request is legitimate.
+Currently, `GitHub <https://developer.github.com/webhooks/securing/>`__ and `GitLab <https://docs.gitlab.com/ee/user/project/integrations/webhooks.html#validate-payloads-by-using-a-secret-token>`__
+offer a way to check this.
+
+Troubleshooting
+---------------
+
+Debugging webhooks
+^^^^^^^^^^^^^^^^^^
+
+If you are experiencing problems with an existing webhook, you may be able to
+use the integration detail page to help debug the issue. Each project
+integration, such as a webhook or the generic API endpoint, stores the HTTP
+exchange that takes place between Read the Docs and the external source. You'll
+find a list of these exchanges in any of the integration detail pages.
+
+
+Webhook activation failed. Make sure you have the necessary permissions
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If you find this error,
+make sure your user has permissions over the repository.
+In case of GitHub,
+check that you have granted access to the Read the Docs `OAuth App`_ to your organization.
+
+.. _OAuth App: https://github.com/settings/applications
+
+
+My project isn't automatically building
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If your project isn't automatically building, you can check your integration on
+Read the Docs to see the payload sent to our servers. If there is no recent
+activity on your Read the Docs project webhook integration, then it's likely
+that your VCS provider is not configured correctly. If there is payload
+information on your Read the Docs project, you might need to verify that your
+versions are configured to build correctly.
diff --git a/docs/user/index.rst b/docs/user/index.rst
@@ -78,11 +78,11 @@ to help you create fantastic documentation for your project.
    /localization
    /choosing-a-site
    /build-notifications
+   /integrations
    /custom-domains
    /pull-requests
    /downloadable-documentation
 
-
 .. toctree::
    :maxdepth: 2
    :hidden:
@@ -113,7 +113,6 @@ and some of the core features of Read the Docs.
 
 * **Overview of core features**:
   :doc:`/features` |
-  :doc:`/integrations` |
   :doc:`/custom-domains` |
   :doc:`/versions` |
   :doc:`/downloadable-documentation` |
@@ -179,6 +178,7 @@ and how to write successful documentation.
   :doc:`More guides for authors </guides/authors>`
 
 * **For project administrators**:
+  :doc:`Connect Your Git Repository </guides/git-integrations>` |
   :doc:`Manage Custom Domains </guides/custom-domains>` |
   :doc:`/guides/technical-docs-seo-guide` |
   :doc:`/guides/manage-translations-sphinx` |
diff --git a/docs/user/integrations.rst b/docs/user/integrations.rst
