diff --git a/docs/user/continuous-deployment.rst b/docs/user/continuous-deployment.rst index 17083dc0bfc..b8d30d01b35 100644 --- a/docs/user/continuous-deployment.rst +++ b/docs/user/continuous-deployment.rst @@ -2,63 +2,77 @@ :orphan: +=============================== Continuous Documentation Deployment -=================================== +=============================== -Read the Docs is a *Continuous Documentation Deployment* platform for your software project. -Every time you change something in your documentation, Read the Docs will detect your change and build your documentation. +Read the Docs is a *Continuous Documentation Deployment* platform for your software project. +Every time you update your documentation, Read the Docs automatically detects the change and rebuilds your site. -The Continuous Integration and Continuous Deployment (CI/CD) features are configured with your repository provider, -such as GitHub, Bitbucket or GitLab. -With each change committed to your repository, we are notified by the configured *webhook*. +----------------------- +How Continuous Deployment Works +----------------------- -When we receive a *webhook*, we match it to a project's *Integration*, -and the following steps happen: +Read the Docs integrates with repository providers such as **GitHub**, **GitLab**, and **Bitbucket**. +Each time you push a new commit, the configured *webhook* notifies Read the Docs, which then triggers a new build. + +When we receive a webhook, we match it to the project’s *Integration* and perform the following steps: * :doc:`Build ` the latest commit. -* Synchronize your :doc:`versions ` based on the latest tag and branch data in Git. -* Run your :doc:`automation rules`. -* Auto-cancel any currently running builds of the same version. -* Add a log entry to the integration's :guilabel:`Recent Activity`. +* Synchronize your :doc:`versions ` based on new tags and branches in Git. +* Run your :doc:`automation rules `. +* Automatically cancel any currently running builds for the same version. +* Add a log entry to the integration’s :guilabel:`Recent Activity`. + +----------------------- +Documentation as Code +----------------------- + +Read the Docs follows the principle of *Documentation as Code (Docs-as-Code)* — +treating documentation with the same tools, workflows, and discipline as your source code. + +By managing your documentation alongside your codebase, you gain: + +* **Unified reviews:** documentation changes go through the same pull request process. +* **Faster feedback:** preview new docs before merging using :doc:`pull request previews `. +* **Automation:** documentation stays up-to-date automatically after each code change. -Documentation as code ---------------------- +Keeping your documentation integrated with your CI/CD pipeline ensures it evolves with your project — no extra steps, no forgotten updates. -Documentation fits into any CI/CD pipeline by following a process known as *Documentation as Code (Docs as code)*. -This means that the documentation's life cycle is the same as your software project. -By managing these changes in the same life cycle, -you can benefit from **documentation and source code being part of the same code review process**. +----------------------- +Automated Versioning +----------------------- -Having an automated and short feedback loop for your documentation allows you to -keep it updated with minimal effort. -This allows more iteration on documentation, -and increases overall value from the documentation you write. +Read the Docs allows your documentation to stay perfectly aligned with your software’s release cycle. +When you tag a new release in Git, Read the Docs can automatically: -As part of this quick feedback loop, -you can preview documentation changes immediately using :doc:`pull request previews `. +* Create and publish a :doc:`new documentation version `. +* Trigger automation rules via :doc:`/automation-rules`. +* Archive and preserve previous versions for user access. -Automated versioning --------------------- +You can manage versioning automatically or manually depending on your release workflow. +All published versions remain accessible through the :term:`flyout menu` and can be enhanced using :doc:`/addons`. -With Read the Docs you will be able to fully align your project's **release cycle** with your documentation. -For instance, a new version of a software project can build and publish a :doc:`new documentation version `. +----------------------- +Troubleshooting & Verification +----------------------- -When you release a new version for your project, -you are likely also adding a version tag to your Git repository. -These Git events can be configured to build and publish your documentation automatically with :doc:`/automation-rules`. -If you use a versioning scheme, you can configure it as part of the automation process. +If your webhook isn’t triggering builds: -Whether you choose to handle versioning automatically or with manual control is up to you. +1. Verify that your repository is correctly connected under **Project > Integrations**. +2. Check your repository’s webhook settings — you should see a **Read the Docs** webhook. +3. Push a small commit and check your build logs on the Read the Docs dashboard. -Read the Docs will store your version history and make it possible for users to visit archived versions of your documentation. -Your version setup is ultimately captured by the :term:`flyout menu`, -and can be integrated in your documentation with :doc:`/addons`. +Common issues: +- **Webhook not firing:** check OAuth connection or make sure your repo is public. +- **Incorrect version built:** verify your default branch setting. +- **Builds stuck:** use the “Cancel Build” option and re-trigger manually. -.. seealso:: +----------------------- +See Also +----------------------- - :doc:`/guides/setup/git-repo-manual` - Information on setting up your Git repository to make Read the Docs automatically build your documentation project. - :doc:`/automation-rules` - Information on setting up your Git repository to make Read the Docs automatically build your documentation project. - :doc:`/flyout-menu` - Discover the functionality of the Flyout menu and the ways that it can be customized. +* :doc:`/guides/setup/git-repo-manual` — set up your Git repository for automatic builds. +* :doc:`/automation-rules` — configure automated build rules and triggers. +* :doc:`/flyout-menu` — customize your project’s version switcher. +* [Integration Overview](https://docs.readthedocs.io/en/stable/integrations.html)