Document how to specify available templates

astrality/module.py

@@ -215,7 +215,12 @@ def context_section_imports(
             # Insert placeholders
             from_file = self.interpolate_string(context_import['from_file'])
             from_section = self.interpolate_string(context_import['from_section'])
-            to_section = self.interpolate_string(context_import['to_section'])
+
+            # If no `to_section` is specified, use the same section as
+            # `from_section`
+            to_section = self.interpolate_string(
+                context_import.get('to_section', from_section),
+            )
 
             # Get the absolute path
             config_path = self.expand_path(Path(from_file))

astrality/tests/test_module.py

@@ -8,7 +8,7 @@
 
 from astrality import timer
 from astrality.config import generate_expanded_env_dict
-from astrality.module import Module, ModuleManager
+from astrality.module import ContextSectionImport, Module, ModuleManager
 from astrality.resolver import Resolver
 
 
@@ -654,6 +654,49 @@ def test_import_sections_on_startup(config_with_modules, freezer):
     }
 
 
+def test_context_section_imports(folders):
+    module_config = {
+        'module/name': {
+            'on_startup': {
+                'import_context': [
+                    {
+                        'from_file': '/testfile',
+                        'from_section': 'source_section',
+                        'to_section': 'target_section',
+                    }
+                ]
+            },
+            'on_period_change': {
+                'import_context': [
+                    {
+                        'from_file': '/testfile',
+                        'from_section': 'source_section',
+                    }
+                ]
+            },
+        },
+    }
+    module = Module(module_config, *folders)
+    startup_csis = module.context_section_imports('on_startup')
+    expected = (
+        ContextSectionImport(
+            from_config_file=Path('/testfile'),
+            from_section='source_section',
+            into_section='target_section',
+        ),
+    )
+    assert startup_csis == expected
+
+    period_change_csis = module.context_section_imports('on_period_change')
+    expected = (
+        ContextSectionImport(
+            from_config_file=Path('/testfile'),
+            from_section='source_section',
+            into_section='source_section',
+        ),
+    )
+    assert period_change_csis == expected
+
 
 class TestModuleManager:
     def test_invocation_of_module_manager_with_config(self, conf):

docs/configuration.rst

@@ -4,6 +4,8 @@
 Configuration
 =============
 
+.. _config_directory:
+
 The Astrality configuration directory
 =====================================
 The configuration directory for astrality is determined in the following way:

docs/modules.rst

@@ -39,7 +39,34 @@ The default value of ``enabled`` is ``true``.
 
 Templates
 =========
-TODO
+
+Modules define which templates that are *available* for compilation.
+Templates are defined on a per-module-basis, using the ``templates`` keyword.
+
+Each *key* in the ``templates`` dictionary becomes a ``shortname`` for that specific template, used to refer to that template in other parts of your Astrality configuration. More on that later in the :ref:`actions` section of this page.
+
+Each template item has the following available attributes:
+
+    * ``source``: Path to the template.
+    * ``target``: *[Optional]* Path which specifies where to put the *compiled* template. You can skip this option if you do not care where the compiled template is placed, and what it is named. You can still use the compiled result by referencing its ``shortname``, which will be explained :ref:`later <actions>`.
+
+An example of module templates syntax:
+
+.. code-block:: yaml
+
+    module/module_name:
+        templates:
+            template_A:
+                source: templates/A.conf
+            template_B:
+                source: /absolute/path/B.conf
+                target: ${XDG_CONFIG_HOME}/B/config
+
+.. note::
+    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.
 
 .. _events: