Skip to content
This repository has been archived by the owner on Jan 14, 2024. It is now read-only.

Commit

Permalink
#66: Update docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@blackandred
blackandred committed Aug 28, 2021
1 parent aa2ad9a commit 8836441
Show file tree
Hide file tree
Showing 5 changed files with 106 additions and 40 deletions.
60 changes: 60 additions & 0 deletions docs/source/environment.rst
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,60 @@
Working with environment variables
==================================

In a project-focused conception RKD is allowing to define environment variables in three places.

1) Dotenv
---------

:code:`.env` file is loaded on each RKD startup from directory, where :code:`./rkdw` is launched.

2) Document scope
-----------------

When operating on YAML there is a possibility to define a makefile-scoped environment variables, inline and loaded from dotenv file.

.. code:: yaml
version: org.riotkit.rkd/yaml/v1
environment:
STOP: "Police brutality"
env_files:
- .env-prod
tasks: {}
3) Task scope
-------------

.. code:: yaml
version: org.riotkit.rkd/yaml/v1
tasks:
:task1:
environment:
STOP: "Police brutality"
env_files:
- .env-prod
steps: |
echo "STOP: ${STOP}"
4) Operating system scope
-------------------------

Traditional, expected way how to pass the environment variables.

.. code:: bash
STOP="Police brutality" ./rkdw :task1
Priority
--------

Later has higher priority.

1. Dotenv loaded at startup
2. Document scope
3. Task scope
4. Operating system
3 changes: 3 additions & 0 deletions docs/source/extending-tasks.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -115,3 +115,6 @@ To coexist parent and new method in place of :code:`inner_execute` just use one
.. include:: ../../src/php/rkd/php/script.py
:start-after: <sphinx:extending-tasks>
:end-before: # </sphinx:extending-tasks>


.. include:: syntax-reference.rst
1 change: 1 addition & 0 deletions docs/source/index.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -100,6 +100,7 @@ Keep learning
pipelines
project-structure
standardlib/index
environment
usage/index
rts/index

41 changes: 41 additions & 0 deletions docs/source/syntax-reference.rst
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,41 @@
Syntax reference
~~~~~~~~~~~~~~~~

+-------------------------------------------------------------------------+------------------------------------------------------+---------------------------------+---------------------------------------------+
| Simplified Python | Python Class | YAML | Description |
+=========================================================================+======================================================+=================================+=============================================+
| get_steps(task: MultiStepLanguageAgnosticTask) -> List[str]: | get_steps | steps: [""] | List of steps in any language (only if |
| | | | extending MultiStep LanguageAgnosticTask) |
+-------------------------------------------------------------------------+------------------------------------------------------+---------------------------------+---------------------------------------------+
| stdin() | N/A | input: "" | Standard input text |
+-------------------------------------------------------------------------+------------------------------------------------------+---------------------------------+---------------------------------------------+
| @extends(ClassName) decorator on a main method | ClassName(BaseClass) | extends: package.name.ClassName | Which Base Task should be extended |
+-------------------------------------------------------------------------+------------------------------------------------------+---------------------------------+---------------------------------------------+
| execute(task: BaseClassNameTask, ctx: ExecutionContext): | execute(self, ctx: ExecutionContext) | execute: "" | Python code to execute |
+-------------------------------------------------------------------------+------------------------------------------------------+---------------------------------+---------------------------------------------+
| inner_execute(task: BaseClassNameTask, ctx: ExecutionContext): | inner_execute(self, ctx: ExecutionContext) | inner_execute: "" | Python code to execute inside |
| | | | inner_execute (if implemented by Base Task) |
+-------------------------------------------------------------------------+------------------------------------------------------+---------------------------------+---------------------------------------------+
| compile(task: BaseClassNameTask, event: CompilationLifecycleEvent): | compile(self, event: CompilationLifecycleEvent): | N/A | Python code to execute during |
| | | | Context compilation process |
+-------------------------------------------------------------------------+------------------------------------------------------+---------------------------------+---------------------------------------------+
| configure(task: BaseClassNameTask, event: ConfigurationLifecycleEvent): | configure(self, event: ConfigurationLifecycleEvent): | configure: "" | Python code to execute during Task |
| | | | configuration process |
+-------------------------------------------------------------------------+------------------------------------------------------+---------------------------------+---------------------------------------------+
| get_description() | get_description(self) | description: "" | Task description |
+-------------------------------------------------------------------------+------------------------------------------------------+---------------------------------+---------------------------------------------+
| get_group_name() | get_group_name() | N/A | Group name |
+-------------------------------------------------------------------------+------------------------------------------------------+---------------------------------+---------------------------------------------+
| internal=True in TaskDeclaration | internal=True in TaskDeclaration | internal: False | Is task considered |
| | | | internal? (hidden on |
| | | | :tasks list) |
+-------------------------------------------------------------------------+------------------------------------------------------+---------------------------------+---------------------------------------------+
| become in TaskDeclaration (or commandline switch) | become in TaskDeclaration | become: root | Change user for task execution time |
| | (or commandline switch) | | |
+-------------------------------------------------------------------------+------------------------------------------------------+---------------------------------+---------------------------------------------+
| workdir in TaskDeclaration | workdir in TaskDeclaration | workdir: /some/path | Change working directory for task |
| | | | execution time |
+-------------------------------------------------------------------------+------------------------------------------------------+---------------------------------+---------------------------------------------+
| configure_argparse(task: BaseClassNameTask, parser: ArgumentParser) | configure_argparse(self, parser: ArgumentParser) | arguments: {} | Configure argparse.ArgumentParser object |
+-------------------------------------------------------------------------+------------------------------------------------------+---------------------------------+---------------------------------------------+

41 changes: 1 addition & 40 deletions docs/source/syntax.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -37,43 +37,4 @@ Classic Python
.. literalinclude:: syntax/classic/.rkd/makefile.py


Syntax reference
~~~~~~~~~~~~~~~~

+-------------------------------------------------------------------------+------------------------------------------------------+---------------------------------+---------------------------------------------+
| Simplified Python | Python Class | YAML | Description |
+=========================================================================+======================================================+=================================+=============================================+
| get_steps(task: MultiStepLanguageAgnosticTask) -> List[str]: | get_steps | steps: [""] | List of steps in any language (only if |
| | | | extending MultiStep LanguageAgnosticTask) |
+-------------------------------------------------------------------------+------------------------------------------------------+---------------------------------+---------------------------------------------+
| stdin() | N/A | input: "" | Standard input text |
+-------------------------------------------------------------------------+------------------------------------------------------+---------------------------------+---------------------------------------------+
| @extends(ClassName) decorator on a main method | ClassName(BaseClass) | extends: package.name.ClassName | Which Base Task should be extended |
+-------------------------------------------------------------------------+------------------------------------------------------+---------------------------------+---------------------------------------------+
| execute(task: BaseClassNameTask, ctx: ExecutionContext): | execute(self, ctx: ExecutionContext) | execute: "" | Python code to execute |
+-------------------------------------------------------------------------+------------------------------------------------------+---------------------------------+---------------------------------------------+
| inner_execute(task: BaseClassNameTask, ctx: ExecutionContext): | inner_execute(self, ctx: ExecutionContext) | inner_execute: "" | Python code to execute inside |
| | | | inner_execute (if implemented by Base Task) |
+-------------------------------------------------------------------------+------------------------------------------------------+---------------------------------+---------------------------------------------+
| compile(task: BaseClassNameTask, event: CompilationLifecycleEvent): | compile(self, event: CompilationLifecycleEvent): | N/A | Python code to execute during |
| | | | Context compilation process |
+-------------------------------------------------------------------------+------------------------------------------------------+---------------------------------+---------------------------------------------+
| configure(task: BaseClassNameTask, event: ConfigurationLifecycleEvent): | configure(self, event: ConfigurationLifecycleEvent): | configure: "" | Python code to execute during Task |
| | | | configuration process |
+-------------------------------------------------------------------------+------------------------------------------------------+---------------------------------+---------------------------------------------+
| get_description() | get_description(self) | description: "" | Task description |
+-------------------------------------------------------------------------+------------------------------------------------------+---------------------------------+---------------------------------------------+
| get_group_name() | get_group_name() | N/A | Group name |
+-------------------------------------------------------------------------+------------------------------------------------------+---------------------------------+---------------------------------------------+
| internal=True in TaskDeclaration | internal=True in TaskDeclaration | internal: False | Is task considered |
| | | | internal? (hidden on |
| | | | :tasks list) |
+-------------------------------------------------------------------------+------------------------------------------------------+---------------------------------+---------------------------------------------+
| become in TaskDeclaration (or commandline switch) | become in TaskDeclaration | become: root | Change user for task execution time |
| | (or commandline switch) | | |
+-------------------------------------------------------------------------+------------------------------------------------------+---------------------------------+---------------------------------------------+
| workdir in TaskDeclaration | workdir in TaskDeclaration | workdir: /some/path | Change working directory for task |
| | | | execution time |
+-------------------------------------------------------------------------+------------------------------------------------------+---------------------------------+---------------------------------------------+
| configure_argparse(task: BaseClassNameTask, parser: ArgumentParser) | configure_argparse(self, parser: ArgumentParser) | arguments: {} | Configure argparse.ArgumentParser object |
+-------------------------------------------------------------------------+------------------------------------------------------+---------------------------------+---------------------------------------------+
.. include:: syntax-reference.rst

0 comments on commit 8836441

Please sign in to comment.