#66: Initial docs for pipelines

riotkit-org · Aug 27, 2021 · 0ed73f2 · 0ed73f2
1 parent 54ea637
commit 0ed73f2
Show file tree

Hide file tree

Showing 7 changed files with 64 additions and 2 deletions.
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -97,6 +97,7 @@ Keep learning
    syntax
    usage/importing-tasks
    extending-tasks
+   pipelines
    project-structure
    usage/index
    standardlib/index

diff --git a/docs/source/pipelines.rst b/docs/source/pipelines.rst
@@ -0,0 +1,61 @@
+Pipelines
+=========
+
+    Pipeline is a set of Tasks executing in selected order, with optional addition of error handling.
+
+
+@error
+------
+
+Executes a Task or set of Tasks when error happens. Does not affect the final result. After error task is finished the whole execution is stopped, no any more task will execute.
+
+**Syntax:**
+
+.. tabs::
+
+   .. tab:: YAML
+
+      .. code:: yaml
+
+            version: org.riotkit.rkd/yaml/v2
+            pipelines:
+                :upgrade:
+                    - task: ":db:backup"
+                    - task: ":db:stop"
+                    - block:
+                          error: [':notify', '--msg="Failed"']
+                          tasks:
+                              - task: [':db:migrate']
+                    - task: [":db:start"]
+                    - task: [":notify", '--msg', 'Finished']
+
+   .. tab:: Python
+
+      .. code:: python
+
+            from rkd.core.api.syntax import Pipeline, PipelineTask as Task, PipelineBlock as Block, TaskDeclaration
+            from rkd.core.standardlib.core import DummyTask
+            from rkd.core.standardlib.shell import ShellCommandTask
+
+            # ...
+
+            PIPELINES = [
+                Pipeline(
+                    name=':upgrade',
+                    description='Example',
+                    to_execute=[
+                        Task(':db:backup'),
+                        Task(':db:stop'),
+                        Block(error=':notify --msg="Failed"', tasks=[
+                            Task(':db:migrate')
+                        ]),
+                        Task(':db:start'),
+                        Task(':notify', '--msg', 'Finished')
+                    ]
+                )
+            ]
+
+**Example workflow:**
+
+.. image:: rkd-pipeline-error.png
+
diff --git a/docs/source/rkd-pipeline-error.png b/docs/source/rkd-pipeline-error.png
diff --git a/docs/source/rkd-pipeline-rescue.png b/docs/source/rkd-pipeline-rescue.png
diff --git a/docs/source/rkd-pipeline-retry-block.png b/docs/source/rkd-pipeline-retry-block.png
diff --git a/docs/source/rkd-pipeline-retry.png b/docs/source/rkd-pipeline-retry.png
diff --git a/docs/source/standardlib/technical.rst b/docs/source/standardlib/technical.rst
@@ -35,7 +35,7 @@ to create a task by defining a simple method as a callback.
 
 .. literalinclude:: ../../examples/callback/.rkd/makefile.py
 
-.. autoclass:: rkd.standardlib.CallableTask
+.. autoclass:: rkd.core.standardlib.CallableTask
    :members:
 
 :rkd:create-structure
@@ -57,7 +57,7 @@ It was designed to allow to create customized installers for tools based on RKD
 
 Look for "interface methods" in class code, those methods are guaranteed to not change from minor version to minor version.
 
-.. autoclass:: rkd.standardlib.CreateStructureTask
+.. autoclass:: rkd.core.standardlib.CreateStructureTask
    :members:
 
 :file:line-in-file