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

docs/user/automation-rules.rst

@@ -1,67 +1,87 @@
-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 on Git repositories.
+If you are familiar with :term:`GitOps`,
+this might seem familiar.
+The goal of Read the Docs' 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 for documentation projects 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 callback to its Webhook.
+This triggers the creation of a new version.
 
-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 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.
 
 .. note::
 
    Versions can match multiple rules,
    and all matching actions will be performed on the version.
 
+Matching a version in Git
+-------------------------
+
 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
---------------------
+~~~~~~~~~~~~~~~~~~~~
 
 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 a 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.
+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.
+
+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.
+
+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,
+
+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,
+
+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.
 
@@ -82,11 +102,8 @@ Currently, the following actions are available:
 Order
 -----
 
-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.
-
-You can change the order using the up and down arrow buttons.
+When a new webhook event is received from your Git provider,
+All rules with a successful match will have their action triggered in the order they appear on the :guilabel:`Automation Rules` page.
 
 .. note::
 

docs/user/glossary.rst

@@ -11,6 +11,15 @@ Glossary
       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
+      A popular term,
+      denoting the use of code, branches and tags maintained in Git in order to automate building, testing, and deployment.
+      GitOps is often used for infrastructure such as maintaining the configuration code for infrastructure in Git.
+      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>`.
+
    pre-defined build jobs
       Commands executed by Read the Docs when performing the build process.
       They cannot be overwritten by the user.
@@ -28,7 +37,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,3 +29,4 @@ 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

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 rule
+-----------------
+
+#. 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.
+   You might have different rules for unstable versions (pre-releases).
+
+#. 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 discovered.
+
+.. 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?
+     You can test if your rule works in a few minutes without disturbing your readers:
+     If you are using Git tags in order to create new versions,
+     create a Git tag that matches the rule and check if your automation action is triggered.
+     After the experiment,
+     you can delete the Read the Docs version and the Git tag.
+
+
+.. _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 first 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

@@ -240,7 +240,6 @@ out of your documentation and Read the Docs.
    user-defined-redirects
    automatic-redirects
 
-   automation-rules
    canonical-urls
 
 

docs/user/reference/features.rst

@@ -8,4 +8,5 @@ Features
 
    analytics
    /server-side-search/index
+   /automation-rules
    /badges