Add context import documentation

docs/modules.rst

@@ -14,7 +14,7 @@ These modules are used to define:
     Configuration file templates that are available for compilation.
 
 :doc:`timers`
-    Timers can trigger events when certain predefined :ref:`periods` occur.
+    Timers can trigger events when certain predefined :ref:`periods <periods>` occur.
 
 :ref:`actions`
     Tasks to be performed when :ref:`events` occur.
@@ -66,7 +66,7 @@ An example of module templates syntax:
     All relative file paths are interpreted relative to the :ref:`config directory<config_directory>` of Astrality.
 
 .. caution::
-    Defining a ``templates`` section in a module will make those templates *available* for compilation. It will **not** automatically compile them. That must be additionaly specified as an action. See the :ref:`actions` section.
+    Defining a ``templates`` section in a module will make those templates *available* for compilation. It will **not** automatically compile them. That must be additionaly specified as an action. See the :ref:`compilation action <compile_action>` documentation.
 
 .. _events:
 
@@ -110,4 +110,87 @@ Example of module event blocks:
 
 Actions
 =======
+
+Actions are tasks for Astrality to perform, and are placed within :ref:`event blocks <events>` in order to specify *when* to perform them. There are three available ``action`` types:
+
+    :ref:`import_context <context_import_action>`:
+        Import a ``context`` section from a YAML formatted file. ``context`` variables are used as replacement values for placeholders in your :ref:`templates <templates>`. See :ref:`context <context>` for more information.
+
+    :ref:`compile <compile_action>`:
+        Compile a specific :ref:`template <templates>` to its target destination.
+
+    :ref:`run <run_action>`:
+        Execute a shell command, possibly referring to any compiled template and/or the current :ref:`period <periods>` defined by the :ref:`module timer <timers>`.
+
+
+.. _context_import_action:
+
+Context imports
+---------------
+
+Context imports are defined as a list of dictionaries under the ``import_context`` keyword in an :ref:`event block <events>` of a module.
+
+This is best explained with an example. Let us create a color schemes file:
+
+.. code-block:: yaml
+
+    # Source file: $ASTRALITY_CONFIG_HOME/contexts/color_schemes.yaml
+
+    context/gruvbox_dark:
+        background: 282828
+        foreground: ebdbb2
+
+Then let us import the gruvbox color scheme into the "colors" :ref:`context <context>` section:
+
+.. code-block:: yaml
+
+    # Source file: $ASTRALITY_CONFIG_HOME/astrality.yaml
+
+    module/color_scheme:
+        on_startup:
+            import_context:
+                - from_file: contexts/color_schemes.yaml
+                  from_section: gruvbox_dark
+                  to_section: colors
+
+This is functionally equivalent to writing:
+
+.. code-block:: yaml
+
+    # Source file: $ASTRALITY_CONFIG_HOME/astrality.yaml
+
+    context/colors:
+        background: 282828
+        foreground: ebdbb2
+
+.. hint::
+    You may wonder why you would want to use this kind of redirection when definining context variables. The advantages are:
+
+        * You can now use ``{{ colors.foreground }}`` in all your templates instead of ``{{ gruvbox_dark.foreground }}``. Since your templates do not know exactly *which* color scheme you are using, you can easily change it in the future by editing only one line in ``astrality.yaml``.
+
+        * You can use ``import_context`` in a ``on_period_change`` event block in order to change your colorscheme based on the time of day. Perhaps you want to use "gruvbox light" during daylight, but change to "gruvbox dark" after dusk?
+
+The available attributes for ``import_context`` are:
+
+    ``from_file``:
+        A YAML formatted file containing :ref:`context sections <context>`.
+
+    ``from_section``:
+        Which context section to import from the file specified in ``from_file``.
+
+    ``to_section``: *[Optional]*
+        What you want to name the imported context section. If this attribute is omitted, Astrality will use the same name as ``from_section``.
+
+.. _compile_action:
+
+Compile templates
+-----------------
+
+TODO
+
+.. _run_action:
+
+Run shell commands
+------------------
+
 TODO

docs/templating.rst

@@ -3,3 +3,8 @@
 ==========
 Templating
 ==========
+
+.. _context:
+
+Context
+=======