From ec46da109cc51b60a7fdfc501e27b01a7e32c2df Mon Sep 17 00:00:00 2001
From: Frederik Hennig <frederik.hennig@fau.de>
Date: Fri, 21 Feb 2025 15:04:34 +0100
Subject: [PATCH] Add section on header-only mode to docs
---
docs/source/usage/config_and_cli.md | 22 +++++++++++++++++-----
1 file changed, 17 insertions(+), 5 deletions(-)
diff --git a/docs/source/usage/config_and_cli.md b/docs/source/usage/config_and_cli.md
index 80169b1..785ff52 100644
--- a/docs/source/usage/config_and_cli.md
+++ b/docs/source/usage/config_and_cli.md
@@ -42,14 +42,15 @@ The file extensions of the generated files can be modified through
{any}`cfg.extensions.header <FileExtensions.header>`
and {any}`cfg.extensions.impl <FileExtensions.impl>`;
and the output directory of the code generator can be set through {any}`cfg.output_directory <SfgConfig.output_directory>`.
-Header-only code generation can be enabled using {any}`cfg.header_only <SfgConfig.header_only>`.
+The [header-only mode](#header_only_mode) can be enabled using {any}`cfg.header_only <SfgConfig.header_only>`.
:::{danger}
-When running generator scripts through [CMake](#cmake_integration), you should *never* set the file extensions
-and the output directory in the inline configuration.
-Both are managed by the pystencils-sfg CMake module, and setting them manually inside the script will
-lead to an error.
+When running generator scripts through [CMake](#cmake_integration), the file extensions,
+output directory, and header-only mode settings will be managed fully by the pystencils-sfg
+CMake module and the (optional) project configuration module.
+They should therefore not be set in the inline configuration,
+as this will likely lead to errors being raised during code generation.
:::
### Outer Namespace
@@ -89,6 +90,17 @@ with the `--help` flag:
$ python kernels.py --help
```
+(header_only_mode)=
+## Header-Only Mode
+
+When the header-only output mode is enabled,
+the code generator will emit only a header file and no separate implementation file.
+In this case, the composer will automatically place all function, method,
+and kernel definitions in the header file.
+
+Header-only code generation can be enabled by setting the `--header-only` command-line flag
+or the {any}`SfgConfig.header_only` configuration option.
+
(custom_cli_args)=
## Adding Custom Command-Line Options
--
GitLab