documentation for CMake module

docs/index.md

@@ -7,13 +7,11 @@ and your C/C++/Cuda/HIP framework.
 
 ### From Git
 
-Clone the [repository](https://i10git.cs.fau.de/da15siwa/pystencils-sfg) and install the package into your current Python environment
+Install the package into your current Python environment from the git repository using pip
 (usage of virtual environments is strongly encouraged!):
 
 ```bash
-git clone https://i10git.cs.fau.de/da15siwa/pystencils-sfg.git
-cd pystencils-sfg
-pip install .
+pip install git+https://i10git.cs.fau.de/da15siwa/pystencils-sfg.git
 ```
 
 ### From PyPI
@@ -61,3 +59,31 @@ python poisson_smoother.py
 This command will execute the code generator through the `SourceFileGenerator` context manager.
 The code generator takes the name of your Python script, replaces `.py` with `.cpp` and `.h`, and writes
 `poisson_smoother.cpp` and `poisson_smoother.h` into the current directory, ready to be `#include`d.
+
+The above is what we call a *generator script*; a Python script that, when executed, produces a pair
+of source files of the same name, but with different extensions.
+Generator scripts are the primary front-end pattern of *pystencils-sfg*; to learn more about them,
+read the [Usage Guide](usage/generator_scripts.md).
+
+## CMake Integration
+
+*Pystencils-sfg* comes with a CMake module to register generator scripts for on-the-fly code generation.
+With the module loaded, use the function `pystencilssfg_generate_target_sources` inside your `CMakeLists.txt`
+to register one or multiple generator scripts; their outputs will automatically be added to the specified target.
+
+```CMake
+pystencilssfg_generate_target_sources( <target name> 
+    SCRIPTS kernels.py ...
+    FILE_EXTENSIONS .h .cpp
+)
+```
+
+*Pystencils-sfg* makes sure that all generated files are on the project's include path.
+To `#include` them, add the prefix `gen/<target name>`:
+
+```C++
+#include "gen/<target name>/kernels.h"
+```
+
+For details on how to add *pystencils-sfg* to your CMake project, refer to
+[CLI and Build System Integration](usage/cli_and_build_system.md).

docs/usage/cli_and_build_system.md

+
+## Command Line Interface
+
+*pystencils-sfg* exposes not one, but two command line interfaces:
+The *global CLI* offers a few tools meant to be used by build systems,
+while the *generator script* command line interface is meant for a build system to communicate
+with the code generator during on-the-fly generation.
+
+### Global CLI
+
+The global CLI may be accessed either through the `sfg-cli` shell command, or using `python -m pystencilssfg`.
+
+### Generator Script CLI
+
+The [SourceFileGenerator][pystencilssfg.SourceFileGenerator] evaluates a generator script's command line arguments,
+which can be supplied by the user, but more frequently by the build system.
+
+## CMake Integration
+
+*pystencils-sfg* is shipped with a CMake module for on-the-fly code generation during the CMake build process.
+
+### Add the module
+
+To include the module in your CMake source tree, a separate find module is provided.
+You can use the global CLI to obtain the find module; simply run
+
+```shell
+sfg-cli cmake make-find-module
+```
+
+to create the file `FindPystencilsSfg.cmake` in the current directory.
+Add it to the CMake module path, and load the *pystencils-sfg* module via *find_package*:
+
+```CMake
+find_package( PystencilsSfg )
+```
+
+Make sure to set the `Python_ROOT_DIR` cache variable to point to the correct Python interpreter
+(i.e. the virtual environment you have installed *pystencils-sfg* into).
+
+### Add generator scripts
+
+The primary interaction point in CMake is the function `pystencilssfg_generate_target_sources`,
+with the following signature:
+
+```CMake
+pystencilssfg_generate_target_sources( <target> 
+    SCRIPTS script1.py [script2.py ...]
+    [DEPENDS dependency1.py [dependency2.py...]]
+    [FILE_EXTENSIONS <header-extension> <impl-extension>]
+    [HEADER_ONLY])
+```
+
+It registers the generator scripts `script1.py [script2.py ...]` to be executed at compile time using `add_custom_command`
+and adds their output files to the specified `<target>`.
+Any changes in the generator scripts, or any listed dependency, will trigger regeneration.
+The function takes the following options:
+
+ - `SCRIPTS`: A list of generator scripts
+ - `DEPENDS`: A list of dependencies for the generator scripts
+ - `FILE_EXTENSION`: The desired extensions for the generated files
+ - `HEADER_ONLY`: Toggles header-only code generation
+
+### Include generated files
+
+The `pystencils-sfg` CMake module creates a subfolder `sfg_sources/gen` at the root of the build tree
+and writes all generated source files into it. The directory `sfg_sources` is added to the project's include
+path, such that generated header files for a target `<target>` may be included via:
+```C++
+#include "gen/<target>/kernels.h"
+```
+
+### Project Configuration
+
+The *pystencils-sfg* CMake module reads the scoped variable `PystencilsSfg_CONFIGURATOR_SCRIPT` to find
+the *configuration module* that should be passed to the generator scripts.

docs/usage/generator_scripts.md

@@ -42,7 +42,7 @@ still be empty.
 A few notes on configuration:
 
  - The [SourceFileGenerator][pystencilssfg.SourceFileGenerator] parses the script's command line arguments
-   for configuration options (refer to [CLI and Build System Integration](cli.md)).
+   for configuration options (refer to [CLI and Build System Integration](cli_and_build_system.md)).
    If you intend to use command-line parameters in your
    generation script, use [`sfg.context.argv`][pystencilssfg.SfgContext.argv] instead of `sys.argv`.
    There, all arguments meant for the code generator are already removed.

docs/usage/index.md

@@ -10,4 +10,4 @@ is required.
    Generator scripts, which are Python scripts that, when executed, emit *pystencils*-generated code to a header/source
    file pair with the same name as the script.
  - [In-Depth: Building Source Files](building.md)
- - [CLI and Build System Integration](cli.md)
\ No newline at end of file
+ - [CLI and Build System Integration](cli_and_build_system.md)
\ No newline at end of file

mkdocs.yml

@@ -42,7 +42,7 @@ nav:
     - 'Overview': usage/index.md
     - 'Writing Generator Scripts': usage/generator_scripts.md
     - 'In-Depth: Building Source Files': usage/building.md
-    - 'CLI and Build System Integration': usage/cli.md
+    - 'CLI and Build System Integration': usage/cli_and_build_system.md
   - 'API Documentation':
     - 'Overview': api/index.md
     - 'Front End':