readthedocs · astrojuanlu · Oct 15, 2021 · Oct 14, 2021 · Oct 14, 2021 · Oct 13, 2021
diff --git a/docs/api/v3.rst b/docs/api/v3.rst
@@ -1832,7 +1832,7 @@ Embed
 .. http:get::  /api/v3/embed/
 
     Retrieve HTML-formatted content from documentation page or section.
-    Read :doc:`guides/embedding-content` to know more about how to use this endpoint.
+    Read :doc:`/guides/embedding-content` to know more about how to use this endpoint.
 
     **Example request**:
 

diff --git a/docs/connected-accounts.rst b/docs/connected-accounts.rst
@@ -6,7 +6,7 @@ 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:`webhooks`
+* Automatically configure 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
 
@@ -27,7 +27,7 @@ Read the Docs does not generally ask for write permission to your repositories'
 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
 so that you can login to Read the Docs with your connected account credentials
-and to setup :doc:`webhooks`
+and to setup :doc:`/integrations`
 which allow us to build your documentation on every change to your repository.
 
 

diff --git a/docs/development/install.rst b/docs/development/install.rst
@@ -206,7 +206,7 @@ using your GitHub, Bitbucket, or GitLab credentials
 and this makes the process of importing repositories easier.
 
 However, because these services will not be able to connect back to your local development instance,
-:doc:`webhooks </webhooks>` will not function correctly.
+:doc:`incoming webhooks </integrations>` will not function correctly.
 For some services, the webhooks will fail to be added when the repository is imported.
 For others, the webhook will simply fail to connect when there are new commits to the repository.
 

diff --git a/docs/features.rst b/docs/features.rst
@@ -16,7 +16,7 @@ This enables a workflow that we call *Continuous Documentation*:
 **Once you set up your Read the Docs project,
 your users will always have up-to-date documentation.**
 
-Learn more about :doc:`/webhooks`.
+Learn more about :doc:`/integrations`.
 
 Custom Domains & White Labeling
 -------------------------------

diff --git a/docs/guides/developers.rst b/docs/guides/developers.rst
@@ -16,4 +16,4 @@ or customize the documentation appearance.
    conda
    remove-edit-buttons
    build-using-too-many-resources
-   vcs
+   edit-source
diff --git a/docs/guides/vcs.rst → docs/guides/edit-source-links-sphinx.rst b/docs/guides/vcs.rst → docs/guides/edit-source-links-sphinx.rst
@@ -1,24 +1,19 @@
-Version Control System integration on your Sphinx theme
-=======================================================
+Adding "Edit Source" links on your Sphinx theme
+===============================================
 
-.. note::
-
-   We :doc:`plan to implement a new approach </development/design/theme-context>` regarding the Theme Context as a whole,
-   although the VCS documentation page will still be valid, we prefer the users to move in that direction.
-
-
-If you want to integrate editing into your own theme, you will have to declare
-few variables inside your configuration file ``conf.py`` in the ``'html_context'``
-setting, for the template to use them.
+Read the Docs injects some extra variables in the Sphinx ``html_context``
+that are used by `our Sphinx theme`_ to display "edit source" links at the top of all pages.
+You can use these variables in your own Sphinx theme as well.
 
 More information can be found on `Sphinx documentation`_.
 
-.. _`Sphinx documentation`: http://www.sphinx-doc.org/en/1.5.2/config.html#confval-html_context
+.. _`our Sphinx theme`: https://sphinx-rtd-theme.readthedocs.io/
+.. _`Sphinx documentation`: http://www.sphinx-doc.org/en/master/configuration.html#confval-html_context
 
 GitHub
 ------
 
-If you want to integrate GitHub, you can put the following snippet into
+If you want to integrate GitHub, these are the required variables to put into
 your ``conf.py``::
 
     html_context = {
@@ -29,7 +24,7 @@ your ``conf.py``::
         "conf_py_path": "/source/", # Path in the checkout to the docs root
     }
 
-It can be used like this::
+They can be used like this::
 
     {% if display_github %}
         <li><a href="https://github.com/{{ github_user }}/{{ github_repo }}
@@ -40,7 +35,7 @@ It can be used like this::
 Bitbucket
 ---------
 
-If you want to integrate Bitbucket, you can put the following snippet into
+If you want to integrate Bitbucket, these are the required variables to put into
 your ``conf.py``::
 
     html_context = {
@@ -51,7 +46,7 @@ your ``conf.py``::
         "conf_py_path": "/source/", # Path in the checkout to the docs root
     }
 
-It can be used like this::
+They can be used like this::
 
     {% if display_bitbucket %}
         <a href="https://bitbucket.org/{{ bitbucket_user }}/{{ bitbucket_repo }}
@@ -62,7 +57,7 @@ It can be used like this::
 Gitlab
 ------
 
-If you want to integrate Gitlab, you can put the following snippet into
+If you want to integrate Gitlab, these are the required variables to put into
 your ``conf.py``::
 
     html_context = {
@@ -73,7 +68,7 @@ your ``conf.py``::
         "conf_py_path": "/source/", # Path in the checkout to the docs root
     }
 
-It can be used like this::
+They can be used like this::
 
     {% if display_gitlab %}
         <a href="https://{{ gitlab_host|default("gitlab.com") }}/

diff --git a/docs/guides/importing-private-repositories.rst b/docs/guides/importing-private-repositories.rst
@@ -119,7 +119,7 @@ Webhooks
 --------
 
 To build your documentation on every commit,
-you'll need to manually add a webhook, see :doc:`/webhooks`.
+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 <webhooks:using the generic api integration>`.
+using our :ref:`generic webhook <integrations:using the generic api integration>`.
diff --git a/docs/index.rst b/docs/index.rst
@@ -13,7 +13,7 @@ Never out of sync |:arrows_counterclockwise:|
     whether that is Git, Mercurial, Bazaar, or Subversion,
     Read the Docs will automatically build your docs
     so your code and documentation are always up-to-date.
-    Read more about :doc:`/webhooks`.
+    Read more about :doc:`/integrations`.
 
 Multiple versions |:card_index_dividers:|
     Read the Docs can host and build multiple versions of your docs
@@ -75,7 +75,7 @@ Learn more about configuring your automated documentation builds
 and some of the core features of Read the Docs.
 
 * **Overview of core features**:
-  :doc:`Incoming webhooks </webhooks>` |
+  :doc:`/integrations` |
   :doc:`/custom_domains` |
   :doc:`/versions` |
   :doc:`/downloadable-documentation` |
@@ -87,8 +87,7 @@ and some of the core features of Read the Docs.
   :doc:`/user-defined-redirects`
 
 * **Connecting with GitHub, BitBucket, or GitLab**:
-  :doc:`Connecting your VCS account </connected-accounts>` |
-  :doc:`VCS webhooks </webhooks>`
+  :doc:`Connecting your VCS account </connected-accounts>`
 
 * **Read the Docs build process**:
   :doc:`Configuration reference </config-file/index>` |
@@ -106,7 +105,7 @@ and some of the core features of Read the Docs.
    :caption: Feature Overview
 
    /config-file/index
-   /webhooks
+   /integrations
    /custom_domains
    /versions
    /downloadable-documentation

diff --git a/docs/webhooks.rst → docs/integrations.rst b/docs/webhooks.rst → docs/integrations.rst
@@ -1,48 +1,43 @@
-Incoming Webhooks and Automation
-================================
+Integrations
+============
 
-The primary method that Read the Docs uses to detect changes to your
-documentation and versions is through the use of *webhooks*. Webhooks are configured with
-your repository provider, such as GitHub, Bitbucket or GitLab, 
+Read the Docs provides integrations with several VCS providers to detect changes to your
+documentation and versions, mainly using *webhooks*.
+Integrations are configured with your repository provider,
+such as GitHub, Bitbucket or GitLab,
 and with each change to your repository, Read the Docs is notified. When we
-receive a webhook notification, we determine if the change is related to an
+receive an integration notification, we determine if the change is related to an
 active version for your project, and if it is, a build is triggered for that
 version.
 
-Webhook Integrations
---------------------
-
-You'll find a list of configured webhook integrations on your project's :guilabel:`Admin`
+You'll find a list of configured integrations on your project's :guilabel:`Admin`
 dashboard, under :guilabel:`Integrations`. You can select any of these integrations to
 see the *integration detail page*. This page has additional configuration
-details and a list of HTTP exchanges that have taken place for the integration.
-
-You need this information for the URL, webhook, or Payload URL needed by the
-repository provider such as GitHub, GitLab, or Bitbucket.
+details and a list of HTTP exchanges that have taken place for the integration,
+including the Payload URL needed by the repository provider
+such as GitHub, GitLab, or Bitbucket.
 
-.. _webhook-creation:
-
-Webhook Creation
-----------------
+Integration Creation
+--------------------
 
 If you have :doc:`connected your Read the Docs account </connected-accounts>` to GitHub, Bitbucket, or GitLab,
-**a webhook will be set up automatically for your repository**. However, if your
+**an integration will be set up automatically for your repository**. However, if your
 project was not imported through a connected account, you may need to
-manually configure a webhook for your project.
+manually configure an integration for your project.
 
-To manually set up a webhook, go to :guilabel:`Admin` > :guilabel:`Integrations` >  :guilabel:`Add integration`
+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 webhook with your provider -- these steps vary depending on the provider.
+Use this URL when setting up a new integration with your provider -- these steps vary depending on the provider.
 
 .. note::
 
    If your account is connected to the provider,
-   we'll try to setup the webhook automatically.
-   If something fails, you can still setup the webhook manually.
+   we'll try to setup the integration automatically.
+   If something fails, you can still setup the integration manually.
 
 .. _webhook-integration-github:
 
@@ -231,52 +226,3 @@ versions are configured to build correctly.
 Either way, it may help to either resync your webhook integration (see
 `Resyncing webhooks`_ for information on this process), or set up an entirely
 new webhook integration.
-
-.. _webhook-github-services:
-
-I was warned I shouldn't use GitHub Services
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Last year, GitHub announced that effective Jan 31st, 2019, GitHub Services will stop
-working [1]_. This means GitHub will stop sending notifications to Read the Docs
-for projects configured with the ``ReadTheDocs`` GitHub Service. If your project
-has been configured on Read the Docs for a long time, you are most likely still
-using this service to automatically build your project on Read the Docs.
-
-In order for your project to continue automatically building, you will need to
-configure your GitHub repository with a new webhook. You can use either a
-connected GitHub account and a :ref:`GitHub webhook integration <webhook-integration-github>`
-on your Read the Docs project, or you can use a
-:ref:`generic webhook integration <webhook-integration-generic>` without a connected
-account.
-
-.. [1] https://developer.github.com/changes/2018-04-25-github-services-deprecation/
-
-.. _webhook-deprecated-endpoints:
-
-I was warned that my project won't automatically build after April 1st
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-In addition to :ref:`no longer supporting GitHub Services <webhook-github-services>`,
-we have decided to no longer support several other legacy incoming webhook
-endpoints that were used before we introduced project webhook integrations. When
-we introduced our webhook integrations, we added several features and improved
-security for incoming webhooks and these features were not added to our legacy
-incoming webhooks. New projects have not been able to use our legacy incoming
-webhooks since, however if you have a project that has been established for a
-while, you may still be using these endpoints.
-
-After March 1st, 2019, we will stop accepting incoming webhook notifications for
-these legacy incoming webhooks. Your project will need to be reconfigured and
-have a webhook integration configured, pointing to a new webhook with your VCS
-provider.
-
-In particular, the incoming webhook URLs that will be removed are:
-
-* ``https://readthedocs.org/build``
-* ``https://readthedocs.org/bitbucket``
-* ``https://readthedocs.org/github`` (as noted :ref:`above <webhook-github-services>`)
-* ``https://readthedocs.org/gitlab``
-
-In order to establish a new project webhook integration, :ref:`follow
-the directions for your VCS provider <webhook-creation>`
diff --git a/docs/intro/import-guide.rst b/docs/intro/import-guide.rst
@@ -49,7 +49,7 @@ Add an optional homepage URL and some tags, and then click **Next**.
 Once your project is created, you'll need to manually configure the repository
 webhook if you would like to have new changes trigger builds for your
 project on Read the Docs. Go to your project's :guilabel:`Admin` > :guilabel:`Integrations` page to
-configure a new webhook, or see :ref:`our steps for webhook creation <webhooks:Webhook Creation>`
+configure a new webhook, or see :ref:`our steps for webhook creation <integrations:Integration Creation>`
 for more information on this process.
 
 .. note::

diff --git a/docs/pull-requests.rst b/docs/pull-requests.rst
@@ -73,8 +73,8 @@ Troubleshooting
    OAuth App to your personal or organization GitHub account.
    Learn more about this in our :ref:`github-permission-troubleshooting` section.
 
-   Also make sure your webhook is properly setup
-   to handle events related to pull requests. You can setup or ``re-sync`` the webhook from your projects admin dashboard.
-   Learn more about setting up webhooks from our :doc:`Webhook Documentation </webhooks>`.
+   Also make sure your webhook integration is properly setup
+   to handle events related to pull requests. You can setup or ``re-sync`` the integration from your projects admin dashboard.
+   Learn more about setting up integrations from our :doc:`integrations documentation </integrations>`.
 
 .. _OAuth App: https://github.com/settings/applications
diff --git a/docs/versions.rst b/docs/versions.rst
@@ -11,7 +11,7 @@ we also create a ``stable`` version, tracking your most recent release.
 If you want a custom ``stable`` version,
 create either a tag or branch in your project with that name.
 
-When you have :doc:`/webhooks` configured for your repository,
+When you have :doc:`/integrations` configured for your repository,
 we will automatically build each version when you push a commit.
 
 How we envision versions working