Add documentation for transformations module. Fix some doc comments.

docs/source/backend/index.rst

@@ -14,6 +14,7 @@ who wish to customize or extend the behaviour of the code generator in their app
     iteration_space
     translation
     platforms
+    transformations
     jit
 
 Internal Representation

docs/source/backend/transformations.rst

+*******************
+AST Transformations
+*******************
+
+`pystencils.backend.transformations`
+
+.. automodule:: pystencils.backend.transformations

src/pystencils/backend/kernelcreation/context.py

@@ -161,7 +161,7 @@ class KernelCreationContext:
     def duplicate_symbol(self, symb: PsSymbol) -> PsSymbol:
         """Canonically duplicates the given symbol.
 
-        A new symbol with the same data type an name ``symb.name + "__<counter>"`` is created,
+        A new symbol with the same data type, and new name ``symb.name + "__<counter>"`` is created,
         added to the symbol table, and returned.
         The ``counter`` reflects the number of previously created duplicates of this symbol.
         """

src/pystencils/backend/transformations/__init__.py

@@ -3,15 +3,15 @@ This module contains various transformation and optimization passes that can be
 executed on the backend AST.
 
 Canonical Form
-^^^^^^^^^^^^^^
+==============
 
 Many transformations in this module require that their input AST is in *canonical form*.
 This means that:
 
- - Each symbol, constant, and expression node is annotated with a data type;
- - Each symbol has at most one declaration;
- - Each symbol that is never written to apart from its declaration has a ``const`` type; and
- - Each symbol whose type is *not* ``const`` has at least one non-declaring assignment.
+- Each symbol, constant, and expression node is annotated with a data type;
+- Each symbol has at most one declaration;
+- Each symbol that is never written to apart from its declaration has a ``const`` type; and
+- Each symbol whose type is *not* ``const`` has at least one non-declaring assignment.
 
 The first requirement can be ensured by running the `Typifier` on each newly constructed subtree.
 The other three requirements are ensured by the `CanonicalizeSymbols` pass,
@@ -23,6 +23,53 @@ to prove their legality.
 
 Certain transformations, like the auto-vectorizer (TODO), state additional requirements, e.g.
 the absence of loop-carried dependencies.
+
+Transformations
+===============
+
+Canonicalization
+----------------
+
+.. autoclass:: CanonicalizeSymbols
+    :members: __call__
+
+AST Cloning
+-----------
+
+.. autoclass:: CanonicalClone
+    :members: __call__
+
+Simplifying Transformations
+---------------------------
+
+.. autoclass:: EliminateConstants
+    :members: __call__
+
+.. autoclass:: EliminateBranches
+    :members: __call__
+
+Code Motion
+-----------
+
+.. autoclass:: HoistLoopInvariantDeclarations
+    :members: __call__
+
+Loop Reshaping Transformations
+------------------------------
+
+.. autoclass:: ReshapeLoops
+    :members:
+
+
+Code Lowering and Materialization
+---------------------------------
+
+.. autoclass:: EraseAnonymousStructTypes
+    :members: __call__
+
+.. autoclass:: SelectFunctions
+    :members: __call__
+
 """
 
 from .canonicalize_symbols import CanonicalizeSymbols
@@ -30,6 +77,7 @@ from .canonical_clone import CanonicalClone
 from .eliminate_constants import EliminateConstants
 from .eliminate_branches import EliminateBranches
 from .hoist_loop_invariant_decls import HoistLoopInvariantDeclarations
+from .reshape_loops import ReshapeLoops
 from .erase_anonymous_structs import EraseAnonymousStructTypes
 from .select_functions import SelectFunctions
 from .select_intrinsics import MaterializeVectorIntrinsics
@@ -40,6 +88,7 @@ __all__ = [
     "EliminateConstants",
     "EliminateBranches",
     "HoistLoopInvariantDeclarations",
+    "ReshapeLoops",
     "EraseAnonymousStructTypes",
     "SelectFunctions",
     "MaterializeVectorIntrinsics",

src/pystencils/backend/transformations/hoist_loop_invariant_decls.py

@@ -69,7 +69,7 @@ class HoistLoopInvariantDeclarations:
     in particular, each symbol may have at most one declaration.
     To ensure this, a `CanonicalizeSymbols` pass should be run before `HoistLoopInvariantDeclarations`.
 
-    `HoistLoopInvariants` assumes that all `PsMathFunction`s are pure (have no side effects),
+    `HoistLoopInvariantDeclarations` assumes that all `PsMathFunction` s are pure (have no side effects),
     but makes no such assumption about instances of `CFunction`.
     """
 

src/pystencils/backend/transformations/reshape_loops.py

@@ -26,7 +26,7 @@ class ReshapeLoops:
     ) -> tuple[Sequence[PsBlock], PsLoop]:
         """Peel off iterations from the front of a loop.
 
-        Removes `num_iterations` from the front of the given loop and returns them as a sequence of
+        Removes ``num_iterations`` from the front of the given loop and returns them as a sequence of
         independent blocks.
 
         Args:
@@ -36,7 +36,7 @@ class ReshapeLoops:
               be executed, and omit their enclosing conditional.
 
         Returns:
-            (peeled_iters, loop): Tuple containing the peeled-off iterations as a sequence of blocks,
+            Tuple containing the peeled-off iterations as a sequence of blocks,
             and the remaining loop.
         """