From 329f28e2b159f9d30f915706f32736785d59df03 Mon Sep 17 00:00:00 2001
From: Frederik Hennig <frederik.hennig@fau.de>
Date: Fri, 1 Dec 2023 08:47:18 +0100
Subject: [PATCH] Added some documentation to the configuration
---
docs/api/{frontend.md => composition.md} | 4 ---
docs/api/generator.md | 4 +++
mkdocs.yml | 3 +-
src/pystencilssfg/cli.py | 5 +--
.../cmake/modules/PystencilsSfg.cmake | 2 +-
src/pystencilssfg/configuration.py | 31 ++++++++++++++++++-
src/pystencilssfg/generator.py | 1 +
7 files changed, 39 insertions(+), 11 deletions(-)
rename docs/api/{frontend.md => composition.md} (70%)
create mode 100644 docs/api/generator.md
diff --git a/docs/api/frontend.md b/docs/api/composition.md
similarity index 70%
rename from docs/api/frontend.md
rename to docs/api/composition.md
index 9c26e79..02ce9e4 100644
--- a/docs/api/frontend.md
+++ b/docs/api/composition.md
@@ -1,8 +1,4 @@
-::: pystencilssfg.generator.SourceFileGenerator
-
-::: pystencilssfg.configuration.SfgConfiguration
-
::: pystencilssfg.context.SfgContext
::: pystencilssfg.composer.SfgComposer
diff --git a/docs/api/generator.md b/docs/api/generator.md
new file mode 100644
index 0000000..32a0b8e
--- /dev/null
+++ b/docs/api/generator.md
@@ -0,0 +1,4 @@
+
+::: pystencilssfg.configuration
+
+::: pystencilssfg.generator
diff --git a/mkdocs.yml b/mkdocs.yml
index 4a83ee2..caa0430 100644
--- a/mkdocs.yml
+++ b/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
diff --git a/src/pystencilssfg/cli.py b/src/pystencilssfg/cli.py
index 5640be8..972aae1 100644
--- a/src/pystencilssfg/cli.py
+++ b/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 '')
diff --git a/src/pystencilssfg/cmake/modules/PystencilsSfg.cmake b/src/pystencilssfg/cmake/modules/PystencilsSfg.cmake
index 26992cb..8cddd48 100644
--- a/src/pystencilssfg/cmake/modules/PystencilsSfg.cmake
+++ b/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)
diff --git a/src/pystencilssfg/configuration.py b/src/pystencilssfg/configuration.py
index b05ba29..8eaab07 100644
--- a/src/pystencilssfg/configuration.py
+++ b/src/pystencilssfg/configuration.py
@@ -1,3 +1,32 @@
+"""
+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
diff --git a/src/pystencilssfg/generator.py b/src/pystencilssfg/generator.py
index 273d142..cea341b 100644
--- a/src/pystencilssfg/generator.py
+++ b/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.")
--
GitLab