From f36a80ddf2a7b6aefe4567a273a1d2d5137b3ce2 Mon Sep 17 00:00:00 2001
From: Frederik Hennig <frederik.hennig@fau.de>
Date: Fri, 15 Dec 2023 21:11:24 +0100
Subject: [PATCH] source concepts documentation

---
 docs/api/cpp_std.md                           |  8 ++++
 docs/api/generator.md                         |  1 +
 docs/api/index.md                             |  5 +++
 docs/api/source_objects.md                    |  6 +++
 docs/api/tree.md                              | 30 +++++++++++++++
 docs/usage/generator_scripts.md               |  4 +-
 mkdocs.yml                                    | 18 ++++++---
 src/pystencilssfg/composer/basic_composer.py  |  9 ++++-
 src/pystencilssfg/configuration.py            | 37 +++++++++++++++++++
 src/pystencilssfg/generator.py                | 34 -----------------
 .../source_concepts/source_objects.py         | 25 +++++++++++++
 src/pystencilssfg/tree/__init__.py            |  4 ++
 src/pystencilssfg/tree/basic_nodes.py         | 19 ++++++++--
 13 files changed, 153 insertions(+), 47 deletions(-)
 create mode 100644 docs/api/cpp_std.md
 create mode 100644 docs/api/source_objects.md

diff --git a/docs/api/cpp_std.md b/docs/api/cpp_std.md
new file mode 100644
index 0000000..bfd9aaa
--- /dev/null
+++ b/docs/api/cpp_std.md
@@ -0,0 +1,8 @@
+
+::: pystencilssfg.source_concepts.cpp.std_vector_ref
+
+::: pystencilssfg.source_concepts.cpp.mdspan_ref
+
+::: pystencilssfg.source_concepts.cpp.StdVector
+
+::: pystencilssfg.source_concepts.cpp.StdMdspan
diff --git a/docs/api/generator.md b/docs/api/generator.md
index 07128fd..1b2b77f 100644
--- a/docs/api/generator.md
+++ b/docs/api/generator.md
@@ -3,3 +3,4 @@
 
 ::: pystencilssfg.configuration.SfgConfiguration
 
+::: pystencilssfg.configuration.DEFAULT_CONFIG
diff --git a/docs/api/index.md b/docs/api/index.md
index 3dd4689..d3c9905 100644
--- a/docs/api/index.md
+++ b/docs/api/index.md
@@ -13,6 +13,11 @@ These pages document the public API of *pystencils-sfg*.
  - [Source File Components](source_components.md)
  - [Kernel Call Tree](tree.md)
 
+### High-Level Language Concepts
+
+ - [Base Classes](source_objects.md)
+ - [C++ Standard Library](cpp_std.md)
+
 ### Code Generation
 
  - [Emission and Printing](emission.md)
\ No newline at end of file
diff --git a/docs/api/source_objects.md b/docs/api/source_objects.md
new file mode 100644
index 0000000..2ba6d4f
--- /dev/null
+++ b/docs/api/source_objects.md
@@ -0,0 +1,6 @@
+
+::: pystencilssfg.source_concepts.SrcObject
+
+::: pystencilssfg.source_concepts.SrcField
+
+::: pystencilssfg.source_concepts.SrcVector
diff --git a/docs/api/tree.md b/docs/api/tree.md
index e69de29..c50e4de 100644
--- a/docs/api/tree.md
+++ b/docs/api/tree.md
@@ -0,0 +1,30 @@
+
+## Base Classes
+
+::: pystencilssfg.tree.SfgCallTreeNode
+
+::: pystencilssfg.tree.SfgCallTreeLeaf
+
+::: pystencilssfg.tree.SfgEmptyNode
+
+## Utility Nodes
+
+::: pystencilssfg.tree.SfgFunctionParams
+
+::: pystencilssfg.tree.SfgRequireIncludes
+
+## Sequences of Statements
+
+::: pystencilssfg.tree.SfgSequence
+
+::: pystencilssfg.tree.SfgStatements
+
+## Structural and Conditional Constructs
+
+::: pystencilssfg.tree.SfgBlock
+
+## Kernel Calls
+
+::: pystencilssfg.tree.SfgKernelCallNode
+
+
diff --git a/docs/usage/generator_scripts.md b/docs/usage/generator_scripts.md
index da34bad..66b2652 100644
--- a/docs/usage/generator_scripts.md
+++ b/docs/usage/generator_scripts.md
@@ -153,10 +153,10 @@ Extract kernel parameters from C++ objects:
    [`SrcField`][pystencilssfg.source_concepts.SrcField].
    Currently, *pystencils-sfg* provides mappings to 
    [`std::vector`](https://en.cppreference.com/w/cpp/container/vector)
-   (via [`std_vector_ref`][pystencilssfg.source_components.cpp.std_vector_ref])
+   (via [`std_vector_ref`][pystencilssfg.source_concepts.cpp.std_vector_ref])
    and
    [`std::mdspan`](https://en.cppreference.com/w/cpp/container/mdspan)
-   (via [`mdspan_ref`][pystencilssfg.source_components.cpp.mdspan_ref])
+   (via [`mdspan_ref`][pystencilssfg.source_concepts.cpp.mdspan_ref])
    from the C++ standard library.
  - [`map_vector`][pystencilssfg.SfgComposer.map_vector] maps a sequence of scalar numerical values
    (given as `pystencils.TypedSymbol`s) to a vector data type. Currently, only `std::vector` is provided.
diff --git a/mkdocs.yml b/mkdocs.yml
index e92f517..66c52d0 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -45,9 +45,15 @@ nav:
     - 'CLI and Build System Integration': usage/cli.md
   - 'API Documentation':
     - 'Overview': api/index.md
-    - 'Source File Generator': api/generator.md
-    - 'Code Generation Context': api/context.md
-    - 'Composer': api/composer.md
-    - 'Source File Components': api/source_components.md
-    - 'Kernel Call Tree': api/tree.md
-    - 'Emission and Printing': api/emission.md
+    - 'Front End':
+      - 'Source File Generator': api/generator.md
+      - 'Code Generation Context': api/context.md
+      - 'Composer': api/composer.md
+    - 'Source File Modelling':
+      - 'Source File Components': api/source_components.md
+      - 'Kernel Call Tree': api/tree.md
+    - 'High-Level Language Concepts':
+      - 'Base Classes': 'api/source_objects.md'
+      - 'C++ Standard Library': 'api/cpp_std.md'
+    - 'Code Generation':
+      - 'Emission and Printing': api/emission.md
diff --git a/src/pystencilssfg/composer/basic_composer.py b/src/pystencilssfg/composer/basic_composer.py
index 29b8d96..492847a 100644
--- a/src/pystencilssfg/composer/basic_composer.py
+++ b/src/pystencilssfg/composer/basic_composer.py
@@ -193,7 +193,7 @@ class SfgBasicComposer:
 
         Args:
             field: The pystencils field to be mapped
-            src_object: A `SrcField` object representing a field data structure.
+            src_object: A [SrcField][pystencilssfg.source_concepts.SrcField] object representing a field data structure.
         """
         return SfgDeferredFieldMapping(field, src_object)
 
@@ -205,7 +205,12 @@ class SfgBasicComposer:
         return SfgStatements(mapping, (lhs,), (rhs,))
 
     def map_vector(self, lhs_components: Sequence[TypedSymbolOrObject], rhs: SrcVector):
-        """Extracts scalar numerical values from a vector data type."""
+        """Extracts scalar numerical values from a vector data type.
+
+        Args:
+            lhs_components: Vector components as a list of symbols.
+            rhs: A [SrcVector][pystencilssfg.source_concepts.SrcVector] object representing a vector data structure.
+        """
         return make_sequence(
             *(
                 rhs.extract_component(dest, coord)
diff --git a/src/pystencilssfg/configuration.py b/src/pystencilssfg/configuration.py
index c6c7422..9a8071e 100644
--- a/src/pystencilssfg/configuration.py
+++ b/src/pystencilssfg/configuration.py
@@ -86,6 +86,42 @@ class SfgOutputSpec:
 
 @dataclass
 class SfgConfiguration:
+    """
+    Configuration for the [SfgSourceFileGenerator][pystencilssfg.SourceFileGenerator].
+
+    The source file generator 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 default and project configuration,
+       and 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:
+        # ...
+        return SfgConfiguration(
+            # ...
+        )
+    ```
+
+    The configuration module is passed to the code generation script via the command-line argument
+    `--sfg-config-module`.
+    """
+
     config_source: InitVar[SfgConfigSource | None] = None
 
     header_extension: str | None = None
@@ -147,6 +183,7 @@ DEFAULT_CONFIG = SfgConfiguration(
     codestyle=SfgCodeStyle(),
     output_directory=".",
 )
+"""Default configuration for the [SourceFileGenerator][pystencilssfg.SourceFileGenerator]."""
 
 
 def run_configurator(configurator_script: str):
diff --git a/src/pystencilssfg/generator.py b/src/pystencilssfg/generator.py
index 99339ff..afd79d9 100644
--- a/src/pystencilssfg/generator.py
+++ b/src/pystencilssfg/generator.py
@@ -15,40 +15,6 @@ from .context import SfgContext
 
 class SourceFileGenerator:
     """Context manager that controls the code generation process in generator scripts.
-
-    ## Configuration
-
-    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 default and project configuration,
-       and 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:
-        # ...
-        return SfgConfiguration(
-            # ...
-        )
-    ```
-
-    The configuration module is passed to the code generation script via the command-line argument
-    `--sfg-config-module`.
     """
 
     def __init__(self, sfg_config: SfgConfiguration | None = None):
diff --git a/src/pystencilssfg/source_concepts/source_objects.py b/src/pystencilssfg/source_concepts/source_objects.py
index f86227e..01e98d5 100644
--- a/src/pystencilssfg/source_concepts/source_objects.py
+++ b/src/pystencilssfg/source_concepts/source_objects.py
@@ -58,6 +58,19 @@ TypedSymbolOrObject: TypeAlias = Union[TypedSymbol, SrcObject]
 
 
 class SrcField(SrcObject, ABC):
+    """Represents a C++ data structure that can be mapped to a *pystencils* field.
+
+    Subclasses of `SrcField` are meant to be used in [SfgComposer.map_field][pystencilssfg.SfgComposer.map_field]
+    to produce the necessary mapping code from a high-level C++ field data structure to a pystencils field.
+
+    Subclasses of `SrcField` must implement `extract_ptr`, `extract_size` and `extract_stride`
+    to emit code extracting field pointers and indexing information from the high-level concept.
+
+    Currently, *pystencils-sfg* provides an implementation for the C++ `std::vector` and `std::mdspan` classes via
+    [StdVector][pystencilssfg.source_concepts.cpp.StdVector] and
+    [StdMdspan][pystencilssfg.source_concepts.cpp.StdMdspan].
+    """
+
     def __init__(self, identifier: str, src_type: SrcType):
         super().__init__(identifier, src_type)
 
@@ -90,6 +103,18 @@ class SrcField(SrcObject, ABC):
 
 
 class SrcVector(SrcObject, ABC):
+    """Represents a C++ abstraction of a mathematical vector that can be mapped to a vector of symbols.
+
+    Subclasses of `SrcVector` are meant to be used in [SfgComposer.map_vector][pystencilssfg.SfgComposer.map_vector]
+    to produce the necessary mapping code from a high-level C++ vector data structure to a vector of symbols.
+
+    Subclasses of `SrcVector` must implement `extract_component` to emit code extracting scalar values
+    from the high-level vector.
+
+    Currently, *pystencils-sfg* provides an implementation for the C++ `std::vector` via
+    [StdVector][pystencilssfg.source_concepts.cpp.StdVector].
+    """
+
     @abstractmethod
     def extract_component(
         self, destination: TypedSymbolOrObject, coordinate: int
diff --git a/src/pystencilssfg/tree/__init__.py b/src/pystencilssfg/tree/__init__.py
index d25a5eb..46d42f8 100644
--- a/src/pystencilssfg/tree/__init__.py
+++ b/src/pystencilssfg/tree/__init__.py
@@ -1,5 +1,7 @@
 from .basic_nodes import (
     SfgCallTreeNode,
+    SfgCallTreeLeaf,
+    SfgEmptyNode,
     SfgKernelCallNode,
     SfgBlock,
     SfgSequence,
@@ -11,6 +13,8 @@ from .conditional import SfgBranch, SfgCondition, IntEven, IntOdd
 
 __all__ = [
     "SfgCallTreeNode",
+    "SfgCallTreeLeaf",
+    "SfgEmptyNode",
     "SfgKernelCallNode",
     "SfgSequence",
     "SfgBlock",
diff --git a/src/pystencilssfg/tree/basic_nodes.py b/src/pystencilssfg/tree/basic_nodes.py
index 437afc9..8561759 100644
--- a/src/pystencilssfg/tree/basic_nodes.py
+++ b/src/pystencilssfg/tree/basic_nodes.py
@@ -12,7 +12,10 @@ if TYPE_CHECKING:
 
 
 class SfgCallTreeNode(ABC):
-    """Base class for all nodes comprising SFG call trees."""
+    """Base class for all nodes comprising SFG call trees.
+
+    Any instantiable call tree node must implement `get_code`.
+    """
 
     def __init__(self, *children: SfgCallTreeNode):
         self._children = list(children)
@@ -50,6 +53,11 @@ class SfgCallTreeNode(ABC):
 
 
 class SfgCallTreeLeaf(SfgCallTreeNode, ABC):
+    """A leaf node of the call tree.
+
+    Leaf nodes must implement `required_parameters` for automatic parameter collection.
+    """
+
     @property
     @abstractmethod
     def required_parameters(self) -> set[TypedSymbolOrObject]:
@@ -57,6 +65,11 @@ class SfgCallTreeLeaf(SfgCallTreeNode, ABC):
 
 
 class SfgEmptyNode(SfgCallTreeLeaf):
+    """A leaf node that does not emit any code.
+
+    Empty nodes must still implement `required_parameters`.
+    """
+
     def __init__(self):
         super().__init__()
 
@@ -76,9 +89,9 @@ class SfgStatements(SfgCallTreeLeaf):
 
     Args:
         code_string: Code to be printed out.
-        defined_objects: Objects (as `SrcObject` or `TypedSymbol`) that will be newly defined and visible to
+        defined_params: Objects (as `SrcObject` or `TypedSymbol`) that will be newly defined and visible to
             code in sequence after these statements.
-        required_objects: Objects (as `SrcObject` or `TypedSymbol`) that are required as input to these statements.
+        required_params: Objects (as `SrcObject` or `TypedSymbol`) that are required as input to these statements.
     """
 
     def __init__(
-- 
GitLab