Add user guide sections on namespaces and configuration. Clean up various doc comments.

docs/source/api/composer.rst

@@ -32,6 +32,9 @@ Helper Methods and Builders
 
 .. autofunction:: make_sequence
 
+.. autoclass:: KernelsAdder
+    :members:
+
 .. autoclass:: SfgFunctionSequencer
     :members:
 
@@ -43,3 +46,14 @@ Helper Methods and Builders
 
 .. autoclass:: SfgSwitchBuilder
     :members:
+
+Context and Cursor
+==================
+
+.. module:: pystencilssfg.context
+
+.. autoclass:: SfgContext
+    :members:
+
+.. autoclass:: SfgCursor
+    :members:

docs/source/api/generation.rst

@@ -24,6 +24,9 @@ Categories, Parameter Types, and Special Values
 .. autoclass:: OutputMode
     :members:
 
+.. autoclass:: FileExtensions
+    :members:
+
 .. autoclass:: CodeStyle
     :members:
 

docs/source/api/ir.rst

 Internal Code Representation (`pystencilssfg.ir`)
 =================================================
 
-.. autoclass:: pystencilssfg.SfgContext
+.. automodule:: pystencilssfg.ir
     :members:
 
-.. automodule:: pystencilssfg.ir
+Postprocessing
+--------------
+
+.. automodule:: pystencilssfg.ir.postprocessing
     :members:

docs/source/getting_started.md

@@ -4,7 +4,7 @@ kernelspec:
   name: python3
 ---
 
-(getting_started)=
+(getting_started_guide)=
 # Getting Started
 
 ```{code-cell} ipython3

docs/source/index.md

@@ -36,7 +36,7 @@ getting_started
 :caption: User Guide
 
 usage/how_to_composer
-C++ API Modelling <usage/api_modelling>
+usage/api_modelling
 usage/config_and_cli
 usage/project_integration
 usage/tips_n_tricks

docs/source/installation.md

@@ -42,4 +42,4 @@ You should see an output like `0.1a4+...`.
 
 ## Next Steps
 
-Move on to [](#getting_started) for a guide on how to author simple generator scripts.
+Move on to [](#getting_started_guide) for a guide on how to author simple generator scripts.

docs/source/usage/api_modelling.md

@@ -5,7 +5,7 @@ kernelspec:
 ---
 
 (how_to_cpp_api_modelling)=
-# Modelling C++ APIs in pystencils-sfg
+# How To Reflect C++ APIs
 
 Pystencils-SFG is designed to help you generate C++ code that interfaces with pystencils on the one side,
 and with your handwritten code on the other side.

docs/source/usage/config_and_cli.md

 
-(guide:generator_scripts)=
+(how_to_generator_scripts_config)=
 # Generator Script Configuration and Command-Line Interface
 
 There are several ways to affect the behavior and output of a generator script.
@@ -26,6 +26,47 @@ of the generator script to `gen_src`:
 ```{literalinclude} examples/guide_generator_scripts/inline_config/kernels.py
 ```
 
+For a selection of common configuration options, see [below](#config_options).
+The inline configuration will override any values set by the [project configuration](#config_module)
+and must not conflict with any [command line arguments](#custom_cli_args).
+
+(config_options)=
+## Configuration Options
+
+Here is a selection of common configuration options to be set in the [inline configuration](#inline_config) or
+[project configuration](#config_module).
+
+### Output Options
+
+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>`.
+
+:::{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.
+:::
+
+### Outer Namespace
+
+To specify the outer namespace to which all generated code should be emitted,
+set {any}`cfg.outer_namespace <SfgConfig.outer_namespace>`.
+
+### Code Style and Formatting
+
+ - Modify the values in the {any}`cfg.code_style <CodeStyle>` category to affect
+   certain formatting aspects of the generated code.
+ - To change, enforce, or disable auto-formatting of generated code through `clang-format`,
+   take a look at the {any}`cfg.clang_format <ClangFormatOptions>` category.
+ - Clang-format will, by default, sort `#include` statements alphabetically and separate
+   local and system header includes.
+   To override this, you can set a custom sorting key for `#include` sorting via
+   {any}`cfg.code_style.includes_sorting_key <CodeStyle.includes_sorting_key>`.
+
 (cmdline_options)=
 ## Command-Line Options
 

docs/source/usage/how_to_composer.md

@@ -236,6 +236,41 @@ with SourceFileGenerator() as sfg:
     )
 ```
 
+## Namespaces
+
+C++ uses namespaces to structure code and group entities.
+By default, pystencils-sfg emits all code into the global namespace.
+For instructions on how to change the outermost namespace used by the `SourceFileGenerator`,
+see [](#how_to_generator_scripts_config).
+
+Starting from the outermost namespace, nested namespaces can be entered and exited during
+code generation.
+To enter a new namespace, use `sfg.namespace` in one of two ways:
+
+ - Simply calling `sfg.namespace("my_namespace")` and ignoring its return value will cause the
+   generator script to use the given namespace for the rest of its execution;
+ - Calling `sfg.namespace("my_namespace")` in a `with` statement will activate the given namespace
+   only for the duration of the managed block.
+
+To illustrate, the following snippet activates the namespace `mylib::generated` for the entire
+length of the generator script, and then enters and exits the nested namespace `mylib::generated::detail`:
+
+```{code-cell} ipython3
+with SourceFileGenerator() as sfg:
+    sfg.namespace("mylib::generated")
+
+    sfg.code("/* Generated code in outer namespace */")
+
+    with sfg.namespace("detail"):
+        sfg.code("/* Implementation details in the inner namespace */")
+
+    sfg.code("/* More code in the outer namespace */")
+```
+
+## Kernels and Kernel Parameter Mappings
+
+
+
 :::{admonition} To Do
 
  - Creating and calling kernels

src/pystencilssfg/composer/basic_composer.py

@@ -120,7 +120,7 @@ class KernelsAdder:
         config: CreateKernelConfig | None = None,
     ):
         """Creates a new pystencils kernel from a list of assignments and a configuration.
-        This is a wrapper around `pystencils.create_kernel`
+        This is a wrapper around `create_kernel <pystencils.codegen.create_kernel>`
         with a subsequent call to `add`.
         """
         if config is None:
@@ -496,7 +496,7 @@ class SfgBasicComposer(SfgIComposer):
 
         Args:
             switch_arg: Argument to the `switch()` statement
-            autobreak: Whether to automatically print a `break;` at the end of each case block
+            autobreak: Whether to automatically print a ``break;`` at the end of each case block
         """
         return SfgSwitchBuilder(switch_arg, autobreak=autobreak)
 
@@ -511,7 +511,7 @@ class SfgBasicComposer(SfgIComposer):
 
         Args:
             field: The pystencils field to be mapped
-            src_object: A `IFieldIndexingProvider` object representing a field data structure.
+            src_object: An object representing a field data structure.
             cast_indexing_symbols: Whether to always introduce explicit casts for indexing symbols
         """
         return SfgDeferredFieldMapping(
@@ -549,7 +549,8 @@ def make_sequence(*args: SequencerArg) -> SfgSequence:
     """Construct a sequence of C++ code from various kinds of arguments.
 
     `make_sequence` is ubiquitous throughout the function building front-end;
-    among others, it powers the syntax of `SfgComposer.function` and `SfgComposer.branch`.
+    among others, it powers the syntax of `SfgBasicComposer.function`
+    and `SfgBasicComposer.branch`.
 
     `make_sequence` constructs an abstract syntax tree for code within a function body, accepting various
     types of arguments which then get turned into C++ code. These are

src/pystencilssfg/composer/custom.py

@@ -8,7 +8,7 @@ if TYPE_CHECKING:
 
 class CustomGenerator(ABC):
     """Abstract base class for custom code generators that may be passed to
-    `SfgComposer.generate`."""
+    `SfgBasicComposer.generate`."""
 
     @abstractmethod
     def generate(self, sfg: SfgComposer) -> None: ...

src/pystencilssfg/generator.py

@@ -18,8 +18,8 @@ class SourceFileGenerator:
     """Context manager that controls the code generation process in generator scripts.
 
     The `SourceFileGenerator` must be used as a context manager by calling it within
-    a ``with`` statement in the top-level code of a generator script (see :ref:`guide:generator_scripts`).
-    Upon entry to its context, it creates an :class:`SfgComposer` which can be used to populate the generated files.
+    a ``with`` statement in the top-level code of a generator script.
+    Upon entry to its context, it creates an `SfgComposer` which can be used to populate the generated files.
     When the managed region finishes, the code files are generated and written to disk at the locations
     defined by the configuration.
     Existing copies of the target files are deleted on entry to the managed region,

src/pystencilssfg/ir/postprocessing.py

@@ -217,6 +217,8 @@ class SfgDeferredParamSetter(SfgDeferredNode):
 
 
 class SfgDeferredFieldMapping(SfgDeferredNode):
+    """Deferred mapping of a pystencils field to a field data structure."""
+
     def __init__(
         self,
         psfield: Field,