Added some documentation to the configuration

docs/api/frontend.md → docs/api/composition.md

 
-::: pystencilssfg.generator.SourceFileGenerator
-
-::: pystencilssfg.configuration.SfgConfiguration
-
 ::: pystencilssfg.context.SfgContext
 
 ::: pystencilssfg.composer.SfgComposer

docs/api/generator.md

+
+::: pystencilssfg.configuration
+
+::: pystencilssfg.generator

mkdocs.yml

@@ -43,5 +43,6 @@ nav:
     - 'CLI and Build System Integration': usage/cli.md
   - 'API Documentation':
     - 'Overview': api/index.md
-    - 'Source File Generator Front-End': api/frontend.md
+    - 'Source File Generator': api/generator.md
+    - 'Composer and Source File Components': api/composition.md
     - 'Kernel Call Tree': api/tree.md

src/pystencilssfg/cli.py

@@ -74,10 +74,7 @@ def list_files(args):
 
     from .emitters import HeaderSourcePairEmitter
 
-    emitter = HeaderSourcePairEmitter(basename,
-                                      config.header_extension,
-                                      config.impl_extension,
-                                      config.output_directory)
+    emitter = HeaderSourcePairEmitter(config.get_output_spec(basename))
 
     print(args.sep.join(emitter.output_files), end=os.linesep if args.newline else '')
 

src/pystencilssfg/cmake/modules/PystencilsSfg.cmake

@@ -55,7 +55,7 @@ function(pystencilssfg_generate_target_sources TARGET)
 
     if(DEFINED PystencilsSfg_CONFIGURATOR_SCRIPT)
         cmake_path(ABSOLUTE_PATH PystencilsSfg_CONFIGURATOR_SCRIPT OUTPUT_VARIABLE configscript)
-        list(APPEND generatorArgs "--sfg-configurator=${configscript}")
+        list(APPEND generatorArgs "--sfg-config-module=${configscript}")
     endif()
 
     if(DEFINED _pssfg_FILE_EXTENSIONS)

src/pystencilssfg/configuration.py

+"""
+The [source file generator][pystencilssfg.SourceFileGenerator] draws configuration from a total of four sources:
+
+ - The [default configuration][pystencilssfg.configuration.DEFAULT_CONFIG];
+ - The project configuration;
+ - Command-line arguments;
+ - The user configuration passed to the constructor of `SourceFileGenerator`.
+
+They take precedence in the following way:
+
+ - Project configuration overrides the default configuration
+ - Command line arguments override the project configuration
+ - User configuration overrides all, but must not conflict with command-line arguments; otherwise, an error is thrown.
+
+### Project Configuration via Configurator Script
+
+Currently, the only way to define the project configuration is via a configuration module.
+A configurator module is a Python file defining the following function at the top-level:
+
+```Python
+from pystencilssfg import SfgConfiguration
+
+def sfg_config() -> SfgConfiguration:
+    ...
+```
+
+The configuration module is passed to the code generation script via the command-line argument
+`--sfg-config-module`.
+"""
 # mypy: strict_optional=False
 
 from __future__ import annotations
@@ -174,7 +203,7 @@ def add_config_args_to_parser(parser: ArgumentParser):
                               dest='file_extensions',
                               help="Comma-separated list of file extensions")
     config_group.add_argument("--sfg-header-only", default=None, action='store_true', dest='header_only')
-    config_group.add_argument("--sfg-configurator", type=str, default=None, dest='configurator_script')
+    config_group.add_argument("--sfg-config-module", type=str, default=None, dest='configurator_script')
 
     return parser
 

src/pystencilssfg/generator.py

@@ -11,6 +11,7 @@ from .composer import SfgComposer
 
 
 class SourceFileGenerator:
+    """Context manager that controls the code generation process in generator scripts."""
     def __init__(self, sfg_config: SfgConfiguration | None = None):
         if sfg_config and not isinstance(sfg_config, SfgConfiguration):
             raise TypeError("sfg_config is not an SfgConfiguration.")