diff --git a/docs/api/v3.rst b/docs/api/v3.rst index aaeb0bacc63..5f4ce4a75c1 100644 --- 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 index 4ac43024cfa..74aa9ef2edc 100644 --- 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 index 6f2cf5bb63a..f4e2da5dcf0 100644 --- 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 ` will not function correctly. +:doc:`incoming webhooks ` 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 index 77b8b0cdea1..6b91f57f931 100644 --- 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 index 5fb0d4f91fd..8677ebcd473 100644 --- 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-links-sphinx diff --git a/docs/guides/vcs.rst b/docs/guides/edit-source-links-sphinx.rst similarity index 67% rename from docs/guides/vcs.rst rename to docs/guides/edit-source-links-sphinx.rst index 05b56a2b1f2..0a507f9284c 100644 --- a/docs/guides/vcs.rst +++ b/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 ` 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 %}
  • `. +using our :ref:`generic webhook `. diff --git a/docs/index.rst b/docs/index.rst index d7aadc818d8..fa6482074e8 100644 --- 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 ` | + :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 ` | - :doc:`VCS webhooks ` + :doc:`Connecting your VCS account ` * **Read the Docs build process**: :doc:`Configuration reference ` | @@ -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 b/docs/integrations.rst similarity index 71% rename from docs/webhooks.rst rename to docs/integrations.rst index c05a0acf39c..f41bd1d1187 100644 --- a/docs/webhooks.rst +++ b/docs/integrations.rst @@ -1,48 +1,43 @@ -Incoming Webhooks and Automation -================================ +VCS 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 ` 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///*. -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 ` -on your Read the Docs project, or you can use a -:ref:`generic webhook integration ` 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 `, -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 `) -* ``https://readthedocs.org/gitlab`` - -In order to establish a new project webhook integration, :ref:`follow -the directions for your VCS provider ` diff --git a/docs/intro/import-guide.rst b/docs/intro/import-guide.rst index 0ded5ed3a29..134bf2555ca 100644 --- 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 ` +configure a new webhook, or see :ref:`our steps for webhook creation ` for more information on this process. .. note:: diff --git a/docs/pull-requests.rst b/docs/pull-requests.rst index eaa607920c0..f96dc4a0e51 100644 --- 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 `. + 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 `. .. _OAuth App: https://github.com/settings/applications diff --git a/docs/versions.rst b/docs/versions.rst index 3d61a8c4ca0..c61c607d4f8 100644 --- 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