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,31 @@ The default value of ``enabled`` is ``true``.
 
 Templates
 =========
-TODO
+
+Modules define which templates which are *available* for compilation.
+Templates are specified in the ``templates`` dictionary of your module.
+Each *key* in the dictionary is your ``shortname`` for that specific template. We will make use of this ``shortname`` in the :ref:`actions` section.
+
+* Each template must specify the ``source`` path to the template.
+* You can also specify an optional ``target`` 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, or what it is named. You can still use the compiled result by referencing its ``shortname``, which will be explained :ref:`later <actions>`.
+
+The syntax is as follows:
+
+.. 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: