Docs: Split "Automation rules" into reference and how-to (Diátaxis)

docs/user/automation-rules.rst

@@ -1,96 +1,110 @@
-Automation Rules
+Automation rules
 ================
 
-Automation rules allow project maintainers to automate actions on new branches and tags on repositories.
+Automation rules allow project maintainers to automate actions on new branches and tags in Git repositories.
+If you are familiar with :term:`GitOps`,
+this might seem familiar.
+The goal of automation rules is to be able to control versioning through your Git repository
+and avoid duplicating these efforts on Read the Docs.
 
-Creating an automation rule
----------------------------
+.. seealso::
 
-#. Go to your project dashboard
-#. Click :guilabel:`Admin` > :guilabel:`Automation Rules`
-#. Click on :guilabel:`Add Rule`
-#. Fill in the fields
-#. Click :guilabel:`Save`
+   :doc:`/guides/automation-rules`
+     A practical guide to managing automated versioning of your documentation.
 
-How do they work?
------------------
+   :doc:`/versions`
+     General explanation of how versioning works on Read the Docs
+
+How automation rules work
+-------------------------
 
 When a new tag or branch is pushed to your repository,
-Read the Docs creates a new version.
+Read the Docs receives a webhook.
+We then create a new Read the Docs *version* that matches your new Git *tag or branch*.
 
-All rules are evaluated for this version, in the order they are listed.
-If the version matches the version type and the pattern in the rule,
-the specified action is performed on that version.
+All automation rules are evaluated for this version,
+in the order they are listed.
+If the version **matches** the version type and the pattern in the rule,
+the specified **action** is performed on that version.
+
+.. _TODO: A diagram would be great here in the future, but probably too much for this refactor.
 
 .. note::
 
-   Versions can match multiple rules,
+   Versions can match multiple automation rules,
    and all matching actions will be performed on the version.
 
+Matching a version in Git
+-------------------------
+
+We have a couple predefined ways to match against versions that are created,
+and you can also define your own.
+
 Predefined matches
-------------------
+~~~~~~~~~~~~~~~~~~
 
-Automation rules support several predefined version matches:
+Automation rules support two predefined version matches:
 
 - **Any version**: All new versions will match the rule.
 - **SemVer versions**: All new versions that follow `semantic versioning <https://semver.org/>`__ will match the rule.
 
-User defined matches
---------------------
+Custom matches
+~~~~~~~~~~~~~~
 
 If none of the above predefined matches meet your use case,
 you can use a **Custom match**.
 
 The custom match should be a valid `Python regular expression <https://docs.python.org/3/library/re.html>`__.
 Each new version will be tested against this regular expression.
 
-Actions
--------
+Actions for versions
+--------------------
 
-When a rule matches a new version, the specified action is performed on that version.
+When an automation rule matches a new version,
+the specified action is performed on that version.
 Currently, the following actions are available:
 
-- **Activate version**: Activates and builds the version.
-- **Hide version**: Hides the version. If the version is not active, activates it and builds the version.
-  See :ref:`versions:Version States`.
-- **Make version public**: Sets the version's privacy level to public.
-  See :ref:`versions:privacy levels`.
-- **Make version private**: Sets the version's privacy level to private.
-  See :ref:`versions:privacy levels`.
-- **Set version as default**: Sets the version as default,
-  i.e. the version of your project that `/` redirects to.
-  See more in :ref:`automatic-redirects:Root URL`.
-  It also activates and builds the version.
-- **Delete version**: When a branch or tag is deleted from your repository,
-  Read the Docs will delete it *only if isn't active*.
-  This action allows you to delete *active* versions when a branch or tag is deleted from your repository.
+Activate version
+  Activates and builds the version.
 
-  .. note::
+Hide version
+  Hides the version. If the version is not active, activates it and builds the version.
+  See :ref:`versions:Version states`.
 
-     The default version isn't deleted even if it matches a rule.
-     You can use the ``Set version as default`` action to change the default version
-     before deleting the current one.
+Make version public
+  Sets the version's privacy level to public.
+  See :ref:`versions:Privacy levels`.
 
+Make version private
+  Sets the version's privacy level to private.
+  See :ref:`versions:Privacy levels`.
 
-.. note::
-
-   If your versions follow :pep:`440`,
-   Read the Docs activates and builds the version if it's greater than the current stable version.
-   The stable version is also automatically updated at the same time.
-   See more in :doc:`versions`.
+Set version as default
+  Sets the version as the :term:`default version`.
+  It also activates and builds the version.
+  See :ref:`automatic-redirects:Root URL`.
 
-Order
------
+Delete version
+  When a branch or tag is deleted from your repository,
+  Read the Docs will delete it *only if isn't active*.
+  This action allows you to delete *active* versions when a branch or tag is deleted from your repository.
 
-The order your rules are listed in  :guilabel:`Admin` > :guilabel:`Automation Rules` matters.
-Each action will be performed in that order,
-so first rules have a higher priority.
+There are a couple caveats to these rules that are useful:
 
-You can change the order using the up and down arrow buttons.
+*   The :term:`default version` isn't deleted even if it matches a rule.
+    You can use the ``Set version as default`` action to change the default version
+    before deleting the current one.
+*   If your versions follow :pep:`440`,
+    Read the Docs activates and builds the version if it's greater than the current stable version.
+    The stable version is also automatically updated at the same time.
+    See more in :doc:`versions`.
 
-.. note::
+Order
+-----
 
-   New rules are added at the end (lower priority).
+When a new Read the Docs version is created,
+all rules with a successful match will have their action triggered,
+in the order they appear on the :guilabel:`Automation Rules` page.
 
 Examples
 --------

docs/user/glossary.rst

@@ -1,6 +1,9 @@
 Glossary
 ========
 
+This page includes a number of terms that we use in our documentation,
+so that you have a reference for how we're using them.
+
 .. glossary::
 
    dashboard
@@ -11,10 +14,24 @@ Glossary
       Projects have a *default version*, usually the latest stable version of a project.
       The *default version* is the URL that is redirected to when a users loads the `/` URL for your project.
 
+   Docs as Code
+      A term used to describe the workflow of keeping documentation in a Git repository,
+      along with source code.
+      Popular in the open source software movement,
+      and used by many technology companies.
+
    flyout menu
       Menu displayed on the documentation, readily accessible for readers, containing the list active versions, links to static downloads, and other useful links.
       Read more in our :doc:`/flyout-menu` page.
 
+   GitOps
+      Denotes the use of code maintained in Git to automate building, testing, and deployment of infrastructure.
+      In terms of documentation,
+      GitOps is applicable for Read the Docs,
+      as the configuration for building documentation is stored in ``.readthedocs.yaml``,
+      and rules for publication of documentation can be :doc:`automated </automation-rules>`.
+      Similar to :term:`Docs as Code`.
+
    pre-defined build jobs
       Commands executed by Read the Docs when performing the build process.
       They cannot be overwritten by the user.
@@ -32,7 +49,7 @@ Glossary
    slug
       A unique identifier for a project or version. This value comes from the
       project or version name, which is reduced to lowercase letters, numbers,
-      and hypens. You can retreive your project or version slugs from
+      and hyphens. You can retrieve your project or version slugs from
       :doc:`our API <api/v3>`.
 
    subproject

docs/user/guides/administrators.rst

@@ -29,4 +29,5 @@ have a look at our :doc:`/tutorial/index`.
    setup-single-sign-on-github-gitlab-bitbucket
    setup-single-sign-on-google-email
    manage-read-the-docs-teams
+   automation-rules
    redirects

docs/user/guides/automation-rules.rst

@@ -0,0 +1,84 @@
+How to manage versions automatically
+====================================
+
+In this guide,
+we show you how to define rules to automate creation of new versions on Read the Docs,
+using your Git repository's version logic.
+Automating your versioning on Read the Docs means you only have to handle your versioning logic in Git.
+
+.. seealso::
+
+   :doc:`/versions`
+     Learn more about versioning of documentation in general.
+
+   :doc:`/automation-rules`
+     Reference for all different rules and actions possible with automation.
+
+Adding a new automation rule
+----------------------------
+
+First you need to go to the automation rule creation page:
+
+#. Navigate to :menuselection:`Admin --> Automation Rules`.
+#. Click on :guilabel:`Add Rule` and you will see the following form.
+
+.. image:: /img/screenshot_automation_rules_add.png
+   :alt: Screenshot of the "Add Rule" form
+
+In the :guilabel:`Automation Rule` form, you need to fill in 4 fields:
+
+#. Enter a :guilabel:`Description` that you can refer to later.
+   For example, entering "Create new stable version" is a good title,
+   as it explains the intention of the rule.
+
+#. Choose a :guilabel:`Match`,
+   which is the pattern you wish to detect in either a Git branch or tag.
+
+   * :ref:`Any version <automation-rules:Predefined matches>` matches all values.
+   * :ref:`SemVer versions <automation-rules:Predefined matches>` matches only values that have the `SemVer`_ format.
+   * :ref:`Custom match <automation-rules:User defined matches>` matches your own pattern (entered below).
+     If you choose this option,
+     a field :guilabel:`Custom match` will automatically appear below the drop-down where you can add a regular expression in `Python regex format`_.
+
+#. Choose a :guilabel:`Version type`.
+   You can choose between *Tag* or *Branch*,
+   denoting *Git tag* or *Git branch*.
+
+#. Finally, choose the :guilabel:`Action`:
+
+   * :ref:`Activate version <automation-rules:Actions for versions>`
+   * :ref:`Hide version <automation-rules:Actions for versions>`
+   * :ref:`Set version as default <automation-rules:Actions for versions>`
+   * :ref:`Delete version (on branch/tag deletion) <automation-rules:Actions for versions>`
+
+
+Now your rule is ready and you can press :guilabel:`Save`.
+The rule takes effect immediately when a new version is created,
+but does not apply to old versions.
+
+.. tip::
+
+   Examples of common usage
+     See :ref:`the list of examples <automation-rules:Examples>` for rules that are commonly used.
+
+   Want to test if your rule works?
+     If you are using Git in order to create new versions,
+     create a Git tag or branch that matches the rule and check if your automation action is triggered.
+     After the experiment,
+     you can delete both from Git and Read the Docs.
+
+.. _Python regex format: https://docs.python.org/3/library/re.html
+.. _SemVer: https://semver.org/
+
+Ordering your rules
+-------------------
+
+The order your rules are listed in  :menuselection:`Admin --> Automation Rules` matters.
+Each action will be performed in that order,
+so earlier rules have a higher priority.
+
+You can change the order using the up and down arrow buttons.
+
+.. note::
+
+   New rules are added at the end (lower priority).

docs/user/index.rst

@@ -237,8 +237,6 @@ out of your documentation and Read the Docs.
 
    flyout-menu
    feature-flags
-
-   automation-rules
    canonical-urls
 
 

docs/user/reference/features.rst

@@ -16,5 +16,6 @@ Features
    analytics
    /feature-flags
    /server-side-search/index
+   /automation-rules
    /user-defined-redirects
    /badges