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 9c26e7975fc4452615e954b9aadcea45e2f57b98..02ce9e41777badb2aa3771358a860429b9d3bad5 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 0000000000000000000000000000000000000000..32a0b8e0c14246d5fe444a22e51f51d859604805 --- /dev/null +++ b/docs/api/generator.md @@ -0,0 +1,4 @@ + +::: pystencilssfg.configuration + +::: pystencilssfg.generator diff --git a/mkdocs.yml b/mkdocs.yml index 4a83ee2603d9bac7d8ddc2e0f4b75cf5f3b9afc8..caa04305d4da28695b2b1ffe6ac8da42bafa0123 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 5640be817051c41c35190e10cf1ff0f61ad9b0d4..972aae13259182b66524ccaef3845dbf30aad8e1 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 26992cbb1e90fb5855248327c8233dcee9ff4a45..8cddd48e463769124fa9165a84331f8c262dfd74 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 b05ba299a4272d5057879e964ddd18ce403fddfb..8eaab0796cb74488f551994f2748ee6445f7e9bd 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 273d1421ce90dc2e7400dbf09bdf7029a9da05bb..cea341b5570efa0954b1a6bc8c41f07e4a652049 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.")