Composer API Extensions and How-To Guide

Composer API

This MR brings a first batch of extensions to the composer API, working toward #12

• constexpr, [[attributes]], static on functions / methods
• manually specified function parameter lists

Documentation

Extend documentation (toward #10 ):

• Introduce a monkeypatch module for running the SourceFileGenerator from MyST-notebooks and immediately printing the output into the markdown
• Installation Guide
• Getting Started Guide
• How-To Guide for the Composer
• Separate code generator configuration guide
• Clean up various remaining errors in the documentation and docstrings
• Configure documentation CI task to fail if Sphinx emits warnings

src/pystencilssfg/composer/basic_composer.py

@@ -610,10 +610,10 @@ def make_sequence(*args: SequencerArg) -> SfgSequence:
     return SfgSequence(children)
 
 
-class SfgFunctionSequencer:
-    """Sequencer for constructing free functions.
+class SfgFunctionSequencerBase:
+    """Common base class for function and method sequencers.
 
-    This builder uses call sequencing to specify the function's properties.
+    This builder uses call sequencing to specify the function or method's properties.
 
     Example:
 
@@ -641,12 +641,12 @@ class SfgFunctionSequencer:
         #   Attributes
         self._attributes: list[str] = []
 
-    def returns(self, rtype: UserTypeSpec) -> SfgFunctionSequencer:
+    def returns(self, rtype: UserTypeSpec):
         """Set the return type of the function"""
         self._return_type = create_type(rtype)
         return self
 
-    def params(self, *args: VarLike) -> SfgFunctionSequencer:
+    def params(self, *args: VarLike):
         """Specify the parameters for this function.
 
         Use this to manually specify the function's parameter list.
@@ -657,21 +657,25 @@ class SfgFunctionSequencer:
         self._params = [asvar(v) for v in args]
         return self
 
-    def inline(self) -> SfgFunctionSequencer:
+    def inline(self):
         """Mark this function as ``inline``."""
         self._inline = True
         return self
 
-    def constexpr(self) -> SfgFunctionSequencer:
+    def constexpr(self):
         """Mark this function as ``constexpr``."""
         self._constexpr = True
         return self
 
-    def attr(self, *attrs: str) -> SfgFunctionSequencer:
+    def attr(self, *attrs: str):
         """Add attributes to this function"""
         self._attributes += attrs
         return self
 
+
+class SfgFunctionSequencer(SfgFunctionSequencerBase):
+    """Sequencer for constructing functions."""
+
     def __call__(self, *args: SequencerArg) -> None:
         """Populate the function body"""
         tree = make_sequence(*args)