Refactor documentation

 - update API docs of config system
 - update sidebar toctree with captions

docs/.gitignore

+**/generated

docs/source/_templates/autosummary/entire_class.rst

+{{ fullname | escape | underline}}
+
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ objname }}
+    :members:

docs/source/_templates/autosummary/recursive_class.rst

+{% extends "!autosummary/class.rst" %}
+
+   {% block methods %}
+
+   {% if methods %}
+   .. rubric:: {{ _('Methods') }}
+
+   .. autosummary::
+      :toctree:
+   {% for item in methods %}
+      ~{{ name }}.{{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block attributes %}
+   {% if attributes %}
+   .. rubric:: {{ _('Attributes') }}
+
+   .. autosummary::
+      :toctree:
+   {% for item in attributes %}
+      ~{{ name }}.{{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}

docs/source/api/generation.rst

@@ -5,13 +5,26 @@ Generator Script Interface
 .. autoclass:: pystencilssfg.SourceFileGenerator
     :members:
 
-.. autoclass:: pystencilssfg.SfgConfiguration
-    :members:
+Configuration
+=============
 
-.. autoclass:: pystencilssfg.SfgOutputMode
-    :members:
+.. module:: pystencilssfg.config
 
-.. autoclass:: pystencilssfg.SfgCodeStyle
+.. autoclass:: SfgConfig
     :members:
+    :exclude-members: __init__
+    
+
+Categories, Parameter Types, and Special Values
+-----------------------------------------------
+
+.. autoclass:: _GlobalNamespace
+.. autodata:: GLOBAL_NAMESPACE
+.. autoclass:: OutputMode
+.. autoclass:: CodeStyle
+.. autoclass:: ClangFormatOptions
+
+Option Descriptors
+------------------
 
-.. autoattribute:: pystencilssfg.configuration.DEFAULT_CONFIG
+.. autoclass:: Option

docs/source/api/index.rst

-#############
-API Reference
-#############
-
-These pages provide a reference for the public API of *pystencils-sfg*.
-
-.. toctree::
-    :maxdepth: 1
-    
-    generation
-    composer
-    lang
-    ir
-    errors

docs/source/conf.py

@@ -27,6 +27,7 @@ extensions = [
     "myst_parser",
     "sphinx.ext.autodoc",
     "sphinx.ext.napoleon",
+    "sphinx.ext.autosummary",
     "sphinx.ext.doctest",
     "sphinx.ext.intersphinx",
     "sphinx_autodoc_typehints",
@@ -71,6 +72,7 @@ intersphinx_mapping = {
 
 autodoc_member_order = "bysource"
 autodoc_typehints = "description"
+# autodoc_class_signature = "separated"
 
 #   Doctest Setup
 

docs/source/index.md

@@ -3,9 +3,24 @@
 ```{toctree}
 :maxdepth: 1
 :hidden:
+:caption: User Guide
 
-usage/index
-api/index
+usage/generator_scripts
+usage/cli_and_build_system
+usage/tips_n_tricks
+```
+
+
+```{toctree}
+:maxdepth: 1
+:hidden:
+:caption: API Reference
+
+api/generation
+api/composer
+api/lang
+api/ir
+api/errors
 ```
 
 [![pipeline](https://i10git.cs.fau.de/pycodegen/pystencils-sfg/badges/master/pipeline.svg)](https://i10git.cs.fau.de/pycodegen-/pystencils-sfg/commits/master)
@@ -211,3 +226,33 @@ To `#include` them, add the prefix `gen/<target name>`:
 
 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).
+
+## Learn To Use pystencils-sfg
+
+Here is an overview of user guides for pystencils-sfg available on this site.
+A basic understanding of [pystencils](https://pycodegen.pages.i10git.cs.fau.de/pystencils/index.html)
+is required.
+
+```{card} Writing Generator Scripts
+:link: guide:generator_scripts
+:link-type: ref
+
+Learn about *generator scripts*, the primary usage idiom of *pystencils-sfg*:
+Embedd *pystencils*-generated kernels into C++ source files and augment them with
+arbitrary C++ glue code.
+```
+
+```{card} CLI and Build System Integration
+:link: guide:cli
+:link-type: ref
+
+Learn how to control code generation from the command line
+and how to embedd *pystencils-sfg* into your build system.
+```
+
+```{card} Tips and Tricks
+:link: guide:tips_n_tricks
+:link-type: ref
+
+A collection of various tricks that might come in handy when working with *pystencils-sfg*.
+```

docs/source/usage/examples/.gitignore

 *.cpp
-*.h
+*.h
\ No newline at end of file
+*.hpp
\ No newline at end of file

docs/source/usage/index.md

-# Usage Guides
-
-```{toctree}
-:maxdepth: 1
-:hidden:
-
-generator_scripts
-cli_and_build_system
-tips_n_tricks
-```
-
-These pages provide an overview of how to use the pystencils Source File Generator.
-A basic understanding of [pystencils](https://pycodegen.pages.i10git.cs.fau.de/pystencils/index.html)
-is required.
-
-```{card} Writing Generator Scripts
-:link: guide:generator_scripts
-:link-type: ref
-
-Learn about *generator scripts*, the primary usage idiom of *pystencils-sfg*:
-Embedd *pystencils*-generated kernels into C++ source files and augment them with
-arbitrary C++ glue code.
-```
-
-```{card} CLI and Build System Integration
-:link: guide:cli
-:link-type: ref
-
-Learn how to control code generation from the command line
-and how to embedd *pystencils-sfg* into your build system.
-```
-
-```{card} Tips and Tricks
-:link: guide:tips_n_tricks
-:link-type: ref
-
-A collection of various tricks that might come in handy when working with *pystencils-sfg*.
-```

src/pystencilssfg/__init__.py

 from .config import SfgConfig
-from .generator import SourceFileGenerator
+from .generator import SourceFileGenerator, GLOBAL_NAMESPACE, OutputMode
 from .composer import SfgComposer
 from .context import SfgContext
 from .lang import SfgVar, AugExpr
@@ -7,6 +7,8 @@ from .exceptions import SfgException
 
 __all__ = [
     "SfgConfig",
+    "GLOBAL_NAMESPACE",
+    "OutputMode",
     "SourceFileGenerator",
     "SfgComposer",
     "SfgContext",

src/pystencilssfg/config.py

@@ -92,6 +92,8 @@ class ConfigBase(ABC):
 
 @dataclass
 class FileExtensions(ConfigBase):
+    """Option category containing output file extensions."""
+
     header: Option[str] = Option("hpp")
     """File extension for generated header file."""
 
@@ -108,6 +110,8 @@ class FileExtensions(ConfigBase):
 
 
 class OutputMode(Enum):
+    """Output mode of the source file generator."""
+
     STANDALONE = auto()
     """Generate a header/implementation file pair (e.g. ``.hpp/.cpp``) where the implementation file will
     be compiled to a standalone object."""
@@ -126,6 +130,8 @@ class OutputMode(Enum):
 
 @dataclass
 class CodeStyle(ConfigBase):
+    """Options affecting the code style used by the source file generator."""
+
     indent_width: Option[int] = Option(2)
     """The number of spaces successively nested blocks should be indented with"""
 
@@ -142,6 +148,8 @@ class CodeStyle(ConfigBase):
 
 @dataclass
 class ClangFormatOptions(ConfigBase):
+    """Options affecting the invocation of ``clang-format`` for automatic code formatting."""
+
     code_style: Option[str] = Option("file")
     """Code style to be used by clang-format. Passed verbatim to `--style` argument of the clang-format CLI.
 
@@ -150,10 +158,10 @@ class ClangFormatOptions(ConfigBase):
     """
 
     force: Option[bool] = Option(False)
-    """If set to True, abort code generation if ``clang-format`` binary cannot be found."""
+    """If set to ``True``, abort code generation if ``clang-format`` binary cannot be found."""
 
     skip: Option[bool] = Option(False)
-    """If set to True, skip formatting using ``clang-format``."""
+    """If set to ``True``, skip formatting using ``clang-format``."""
 
     binary: Option[str] = Option("clang-format")
     """Path to the clang-format executable"""
@@ -179,25 +187,58 @@ class _GlobalNamespace: ...  # noqa: E701
 
 
 GLOBAL_NAMESPACE = _GlobalNamespace()
+"""Indicates the C++ global namespace."""
 
 
 @dataclass
 class SfgConfig(ConfigBase):
+    """Configuration options for the `SourceFileGenerator`."""
+
     extensions: FileExtensions = field(default_factory=FileExtensions)
-    """File extensions of the generated files"""
+    """File extensions of the generated files
+
+    Options in this category:
+        .. autosummary::
+            FileExtensions.header
+            FileExtensions.impl
+    """
 
     output_mode: Option[OutputMode] = Option(OutputMode.STANDALONE)
-    """The generator's output mode; defines which files to generate, and the set of legal file extensions."""
+    """The generator's output mode; defines which files to generate, and the set of legal file extensions.
+
+    Possible parameters:
+        .. autosummary::
+            OutputMode.STANDALONE
+            OutputMode.INLINE
+            OutputMode.HEADER_ONLY
+    """
 
     outer_namespace: Option[str | _GlobalNamespace] = Option(GLOBAL_NAMESPACE)
     """The outermost namespace in the generated file. May be a valid C++ nested namespace qualifier
-    (like ``a::b::c``) or `GLOBAL_NAMESPACE` if no outer namespace should be generated."""
+    (like ``a::b::c``) or `GLOBAL_NAMESPACE` if no outer namespace should be generated.
+
+    .. autosummary::
+        GLOBAL_NAMESPACE
+    """
 
     codestyle: CodeStyle = field(default_factory=CodeStyle)
-    """Options affecting the code style emitted by pystencils-sfg."""
+    """Options affecting the code style emitted by pystencils-sfg.
+
+    Options in this category:
+        .. autosummary::
+            CodeStyle.indent_width
+    """
 
     clang_format: ClangFormatOptions = field(default_factory=ClangFormatOptions)
-    """Options governing the code style used by the code generator"""
+    """Options governing the code style used by the code generator
+
+    Options in this category:
+        .. autosummary::
+            ClangFormatOptions.code_style
+            ClangFormatOptions.force
+            ClangFormatOptions.skip
+            ClangFormatOptions.binary
+    """
 
     output_directory: Option[str] = Option(".")
     """Directory to which the generated files should be written."""