From 08130bf740fef9d23d7e9eb0acca3e1994eee85b Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Tue, 13 Aug 2019 20:08:16 -0500 Subject: [PATCH 1/7] Add docs --- docs/Makefile | 2 +- docs/automation-rules.rst | 116 ++++++++++++++++++++++++++++++++++++++ docs/index.rst | 5 ++ 3 files changed, 122 insertions(+), 1 deletion(-) create mode 100644 docs/automation-rules.rst diff --git a/docs/Makefile b/docs/Makefile index 7e97a2c7183..cdb357b38f7 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -2,7 +2,7 @@ # # You can set these variables from the command line. -SPHINXOPTS = -W --keep-going +SPHINXOPTS = -W SPHINXBUILD = sphinx-build PAPER = BUILDDIR = _build diff --git a/docs/automation-rules.rst b/docs/automation-rules.rst new file mode 100644 index 00000000000..2f49058e936 --- /dev/null +++ b/docs/automation-rules.rst @@ -0,0 +1,116 @@ +Automation Rules +================ + +By default when new versions are created, +they are not activated. +So, when a new tag or branch is pushed to your repository, +you need to log in your Read the Docs account to activate it or +do other type of actions over that version. + +To help to automate this tasks you can create an automation rule. + +#. Go to your project :guilabel:`Admin` > :guilabel:`Automation Rules` +#. Click on "Add Rule" button +#. Fill in the fields + + - Description: A description of what the rule does + - Match: What versions the rule should be applied to + - Version type: What type of versions the rule should be applied to + - Action: What action should be applied to matching rules + +#. Click "Save" + +Match +----- + +New versions are matched against the type of match you chose: + +- **All versions**: All new versions. +- **SemVer versions**: All new versions that follow `semantic versioning `__. +- **Custom match**: If none of the above rules match your use case, + you can write a regular expression. + +Custom match +~~~~~~~~~~~~ + +The custom match should be a valid `Python regular expression `__. +Each new version is going to be tested against this regular expression, +if it matches the corresponding action is executed against that version. + +Actions +------- + +Currently we only support the following actions: + +- **Activate version on match**: It activates and builds the version. +- **Set as default version on match**: It activates and builds the version too. + Additionally, it sets the version as default, + i.e. the version of your project that `/` redirects to. + See more in :ref:`automatic-redirects:Root URL`. + +.. note:: + + If your versions follow :pep:`440`, + Read the Docs activates and builds the version if it's greater than the current stable version. + See more in :doc:`versions`. + +Order +----- + +The order your rules are listed in :guilabel:`Admin` > :guilabel:`Automation Rules` matters. +Each action will be executed in that order, +so first rules have a higher priority. + +You can change the order using the up and down arrow buttons. + +.. note:: + + All actions of the rules that the version matches will be executed over that version. + +Examples +-------- + +Activate all new tags +~~~~~~~~~~~~~~~~~~~~~ + +- Match: ``All versions`` +- Version type: ``Tag`` +- Action: ``Activate version on match`` + +Activate only new branches that belong to the ``1.x`` release +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- Custom match: ``^1\.\d+$`` +- Version type: ``Branch`` +- Action: ``Activate version on match`` + +Set as default new tags that have the ``-stable`` or ``-release`` suffix +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- Custom match: ``-(stable)|(release)$`` +- Version type: ``Branch`` +- Action: ``Set as default version on match`` + +.. note:: + + You can also create two rules, one to match ``-stable`` and + other to match ``-release``. + +Activate all new tags and branches that start with ``v`` or ``V`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- Custom match: ``^[vV]`` +- Version type: ``Tag`` +- Action: ``Activate version on match`` + + +- Custom match: ``^[vV]`` +- Version type: ``Branch`` +- Action: ``Activate version on match`` + +Activate all new tags that don't contain the ``-nightly`` suffix +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- Custom match: ``.*(?` | :doc:`Automatic redirects ` +* **Versions** + :doc:`Automation rules ` + * **Topic specific guides**: :doc:`How-to guides ` @@ -142,6 +145,8 @@ out of your documentation and Read the Docs. user-defined-redirects automatic-redirects + automation-rules + guides/index api/index From cd6bb831e637a36260f062719ca2e3840248e06e Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Wed, 14 Aug 2019 09:02:32 -0500 Subject: [PATCH 2/7] Feedback --- docs/automation-rules.rst | 78 ++++++++++++++++++++++++--------------- 1 file changed, 48 insertions(+), 30 deletions(-) diff --git a/docs/automation-rules.rst b/docs/automation-rules.rst index 2f49058e936..5057aeea6d7 100644 --- a/docs/automation-rules.rst +++ b/docs/automation-rules.rst @@ -1,13 +1,15 @@ Automation Rules ================ +Automation rules allow you to execute some actions over new versions. + By default when new versions are created, they are not activated. -So, when a new tag or branch is pushed to your repository, -you need to log in your Read the Docs account to activate it or -do other type of actions over that version. +If you want to activate it and do other type of actions, +you need to log in your Read the Docs account first. -To help to automate this tasks you can create an automation rule. +Creating an automation rule +--------------------------- #. Go to your project :guilabel:`Admin` > :guilabel:`Automation Rules` #. Click on "Add Rule" button @@ -16,42 +18,58 @@ To help to automate this tasks you can create an automation rule. - Description: A description of what the rule does - Match: What versions the rule should be applied to - Version type: What type of versions the rule should be applied to - - Action: What action should be applied to matching rules + - Action: What action should be applied to matching versions #. Click "Save" -Match ------ +How do they work? +----------------- + +When a new tag or branch is pushed to your repository, +Read the Docs creates a new version. + +All rules are run over this version in the order they are listed, +if the version matches the version type and the pattern in the rule, +an action is executed over that version. + +.. note:: + + All actions of the rules that the version matches will be executed over that version. -New versions are matched against the type of match you chose: +Predefined matches +------------------ -- **All versions**: All new versions. -- **SemVer versions**: All new versions that follow `semantic versioning `__. -- **Custom match**: If none of the above rules match your use case, - you can write a regular expression. +There are some predefined matches: -Custom match -~~~~~~~~~~~~ +- **All versions**: All new versions are matched. +- **SemVer versions**: All new versions that follow `semantic versioning `__ are matched. + +User defined matches +-------------------- + +If none of the above matches meet your use case, +choose **Custom match**. The custom match should be a valid `Python regular expression `__. -Each new version is going to be tested against this regular expression, -if it matches the corresponding action is executed against that version. +Each new version is going to be tested against this regular expression. Actions ------- -Currently we only support the following actions: +Actions are the task to be executed over the matching version. +Currently, this actions are available: -- **Activate version on match**: It activates and builds the version. -- **Set as default version on match**: It activates and builds the version too. - Additionally, it sets the version as default, +- **Activate and build version**: It activates and builds the version. +- **Set as default version**: It 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. .. note:: If your versions follow :pep:`440`, - Read the Docs activates and builds the version if it's greater than the current stable version. + Read the Docs activates and builds the version if it's greater than the current stable version, + and updates the stable version. See more in :doc:`versions`. Order @@ -64,8 +82,8 @@ so first rules have a higher priority. You can change the order using the up and down arrow buttons. .. note:: - - All actions of the rules that the version matches will be executed over that version. + + New rules are added at the end (lower priority). Examples -------- @@ -75,21 +93,21 @@ Activate all new tags - Match: ``All versions`` - Version type: ``Tag`` -- Action: ``Activate version on match`` +- Action: ``Activate version`` Activate only new branches that belong to the ``1.x`` release ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - Custom match: ``^1\.\d+$`` - Version type: ``Branch`` -- Action: ``Activate version on match`` +- Action: ``Activate version`` Set as default new tags that have the ``-stable`` or ``-release`` suffix ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - Custom match: ``-(stable)|(release)$`` -- Version type: ``Branch`` -- Action: ``Set as default version on match`` +- Version type: ``Tag`` +- Action: ``Set as default version`` .. note:: @@ -101,16 +119,16 @@ Activate all new tags and branches that start with ``v`` or ``V`` - Custom match: ``^[vV]`` - Version type: ``Tag`` -- Action: ``Activate version on match`` +- Action: ``Activate version`` - Custom match: ``^[vV]`` - Version type: ``Branch`` -- Action: ``Activate version on match`` +- Action: ``Activate version`` Activate all new tags that don't contain the ``-nightly`` suffix ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - Custom match: ``.*(? Date: Wed, 14 Aug 2019 09:05:57 -0500 Subject: [PATCH 3/7] Remove initial it --- docs/automation-rules.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/automation-rules.rst b/docs/automation-rules.rst index 5057aeea6d7..eadd7d23049 100644 --- a/docs/automation-rules.rst +++ b/docs/automation-rules.rst @@ -59,8 +59,8 @@ Actions Actions are the task to be executed over the matching version. Currently, this actions are available: -- **Activate and build version**: It activates and builds the version. -- **Set as default version**: It sets the version as default, +- **Activate and build version**: Activates and builds the version. +- **Set as default version**: 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. From c6cc05adb2bf8d7ac3049d6c1d50ae719b6fa66f Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Wed, 6 Nov 2019 18:37:58 -0500 Subject: [PATCH 4/7] Update docs --- docs/automation-rules.rst | 19 +++++++++++-------- 1 file changed, 11 insertions(+), 8 deletions(-) diff --git a/docs/automation-rules.rst b/docs/automation-rules.rst index eadd7d23049..7803ca8d0df 100644 --- a/docs/automation-rules.rst +++ b/docs/automation-rules.rst @@ -41,17 +41,17 @@ Predefined matches There are some predefined matches: -- **All versions**: All new versions are matched. -- **SemVer versions**: All new versions that follow `semantic versioning `__ are matched. +- **Any version**: All new versions will match. +- **SemVer versions**: All new versions that follow `semantic versioning `__ will match. User defined matches -------------------- -If none of the above matches meet your use case, +If none of the above predefined matches meet your use case, choose **Custom match**. The custom match should be a valid `Python regular expression `__. -Each new version is going to be tested against this regular expression. +Each new version will be tested against this regular expression. Actions ------- @@ -59,8 +59,8 @@ Actions Actions are the task to be executed over the matching version. Currently, this actions are available: -- **Activate and build version**: Activates and builds the version. -- **Set as default version**: Sets the version as default, +- **Activate version**: Activates and builds the version. +- **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. @@ -91,7 +91,7 @@ Examples Activate all new tags ~~~~~~~~~~~~~~~~~~~~~ -- Match: ``All versions`` +- Match: ``Any version`` - Version type: ``Tag`` - Action: ``Activate version`` @@ -107,7 +107,7 @@ Set as default new tags that have the ``-stable`` or ``-release`` suffix - Custom match: ``-(stable)|(release)$`` - Version type: ``Tag`` -- Action: ``Set as default version`` +- Action: ``Set version as default`` .. note:: @@ -129,6 +129,9 @@ Activate all new tags and branches that start with ``v`` or ``V`` Activate all new tags that don't contain the ``-nightly`` suffix ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. TODO: update example if https://github.com/readthedocs/readthedocs.org/issues/6354 is approved. + + - Custom match: ``.*(? Date: Wed, 13 Nov 2019 18:37:30 -0500 Subject: [PATCH 5/7] Apply suggestions from code review Co-Authored-By: Anthony --- docs/automation-rules.rst | 33 +++++++++++++++++---------------- 1 file changed, 17 insertions(+), 16 deletions(-) diff --git a/docs/automation-rules.rst b/docs/automation-rules.rst index 7803ca8d0df..40bdfbd1486 100644 --- a/docs/automation-rules.rst +++ b/docs/automation-rules.rst @@ -1,7 +1,7 @@ Automation Rules ================ -Automation rules allow you to execute some actions over new versions. +Automation rules allow project maintainers to automate actions on new branches and tags on repositories. By default when new versions are created, they are not activated. @@ -11,8 +11,9 @@ you need to log in your Read the Docs account first. Creating an automation rule --------------------------- -#. Go to your project :guilabel:`Admin` > :guilabel:`Automation Rules` -#. Click on "Add Rule" button +#. Go to your project dashboard +#. Click :guilabel:`Admin` > :guilabel:`Automation Rules` +#. Click on :guilabel:`Add Rule` #. Fill in the fields - Description: A description of what the rule does @@ -20,7 +21,7 @@ Creating an automation rule - Version type: What type of versions the rule should be applied to - Action: What action should be applied to matching versions -#. Click "Save" +#. Click :guilabel:`Save` How do they work? ----------------- @@ -28,27 +29,27 @@ How do they work? When a new tag or branch is pushed to your repository, Read the Docs creates a new version. -All rules are run over this version in the order they are listed, -if the version matches the version type and the pattern in the rule, -an action is executed over 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:: - All actions of the rules that the version matches will be executed over that version. +Versions can match multiple rules, and all matching actions will be performed on the version. Predefined matches ------------------ -There are some predefined matches: +Automation rules support several predefined version matches: -- **Any version**: All new versions will match. -- **SemVer versions**: All new versions that follow `semantic versioning `__ will match. +- **Any version**: All new versions will match the rule. +- **SemVer versions**: All new versions that follow `semantic versioning `__ will match the rule. User defined matches -------------------- If none of the above predefined matches meet your use case, -choose **Custom match**. +you can use a **Custom match**. The custom match should be a valid `Python regular expression `__. Each new version will be tested against this regular expression. @@ -56,8 +57,8 @@ Each new version will be tested against this regular expression. Actions ------- -Actions are the task to be executed over the matching version. -Currently, this actions are available: +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. - **Set version as default**: Sets the version as default, @@ -68,8 +69,8 @@ Currently, this actions are available: .. note:: If your versions follow :pep:`440`, - Read the Docs activates and builds the version if it's greater than the current stable version, - and updates the stable version. + 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`. Order From 5b09c63e69d8a7b6117ec9229fa2fcf74a32c4f1 Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Wed, 13 Nov 2019 19:00:05 -0500 Subject: [PATCH 6/7] Better docs --- docs/automation-rules.rst | 25 ++++++++++--------------- 1 file changed, 10 insertions(+), 15 deletions(-) diff --git a/docs/automation-rules.rst b/docs/automation-rules.rst index 40bdfbd1486..c6c26b530d2 100644 --- a/docs/automation-rules.rst +++ b/docs/automation-rules.rst @@ -3,10 +3,9 @@ Automation Rules Automation rules allow project maintainers to automate actions on new branches and tags on repositories. -By default when new versions are created, -they are not activated. -If you want to activate it and do other type of actions, -you need to log in your Read the Docs account first. +When a version is created from a new branch or tag, +automation rules can perform actions like activating the new version, +or setting the new version as the default version. Creating an automation rule --------------------------- @@ -15,12 +14,6 @@ Creating an automation rule #. Click :guilabel:`Admin` > :guilabel:`Automation Rules` #. Click on :guilabel:`Add Rule` #. Fill in the fields - - - Description: A description of what the rule does - - Match: What versions the rule should be applied to - - Version type: What type of versions the rule should be applied to - - Action: What action should be applied to matching versions - #. Click :guilabel:`Save` How do they work? @@ -35,7 +28,8 @@ the specified action is performed on that version. .. note:: -Versions can match multiple rules, and all matching actions will be performed on the version. + Versions can match multiple rules, + and all matching actions will be performed on the version. Predefined matches ------------------ @@ -77,7 +71,7 @@ Order ----- The order your rules are listed in :guilabel:`Admin` > :guilabel:`Automation Rules` matters. -Each action will be executed in that order, +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. @@ -106,14 +100,14 @@ Activate only new branches that belong to the ``1.x`` release Set as default new tags that have the ``-stable`` or ``-release`` suffix ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- Custom match: ``-(stable)|(release)$`` +- Custom match: ``-(stable|release)$`` - Version type: ``Tag`` - Action: ``Set version as default`` .. note:: - You can also create two rules, one to match ``-stable`` and - other to match ``-release``. + You can also create two rules: + one to match ``-stable`` and other to match ``-release``. Activate all new tags and branches that start with ``v`` or ``V`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -122,6 +116,7 @@ Activate all new tags and branches that start with ``v`` or ``V`` - Version type: ``Tag`` - Action: ``Activate version`` +.. Force new line - Custom match: ``^[vV]`` - Version type: ``Branch`` From 25bc3c4dda62581212c6eebcf448afc52ec73564 Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Wed, 13 Nov 2019 19:03:46 -0500 Subject: [PATCH 7/7] Remove redundant text it's already described on `How do they work?` --- docs/automation-rules.rst | 4 ---- 1 file changed, 4 deletions(-) diff --git a/docs/automation-rules.rst b/docs/automation-rules.rst index c6c26b530d2..51bac325230 100644 --- a/docs/automation-rules.rst +++ b/docs/automation-rules.rst @@ -3,10 +3,6 @@ Automation Rules Automation rules allow project maintainers to automate actions on new branches and tags on repositories. -When a version is created from a new branch or tag, -automation rules can perform actions like activating the new version, -or setting the new version as the default version. - Creating an automation rule ---------------------------