From d7843769c16f805dd72e28d6d67c19f072210ff1 Mon Sep 17 00:00:00 2001
From: Frederik Hennig <frederik.hennig@fau.de>
Date: Sun, 1 Dec 2024 16:38:44 +0100
Subject: [PATCH] Refactor documentation
- update API docs of config system
- update sidebar toctree with captions
---
docs/.gitignore | 1 +
.../_templates/autosummary/entire_class.rst | 6 ++
.../autosummary/recursive_class.rst | 26 +++++++++
docs/source/api/generation.rst | 25 +++++++--
docs/source/api/index.rst | 14 -----
docs/source/conf.py | 2 +
docs/source/index.md | 49 ++++++++++++++++-
docs/source/usage/examples/.gitignore | 3 +-
docs/source/usage/index.md | 38 -------------
src/pystencilssfg/__init__.py | 4 +-
src/pystencilssfg/config.py | 55 ++++++++++++++++---
11 files changed, 154 insertions(+), 69 deletions(-)
create mode 100644 docs/.gitignore
create mode 100644 docs/source/_templates/autosummary/entire_class.rst
create mode 100644 docs/source/_templates/autosummary/recursive_class.rst
delete mode 100644 docs/source/api/index.rst
delete mode 100644 docs/source/usage/index.md
diff --git a/docs/.gitignore b/docs/.gitignore
new file mode 100644
index 0000000..09b697c
--- /dev/null
+++ b/docs/.gitignore
@@ -0,0 +1 @@
+**/generated
diff --git a/docs/source/_templates/autosummary/entire_class.rst b/docs/source/_templates/autosummary/entire_class.rst
new file mode 100644
index 0000000..8643ade
--- /dev/null
+++ b/docs/source/_templates/autosummary/entire_class.rst
@@ -0,0 +1,6 @@
+{{ fullname | escape | underline}}
+
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ objname }}
+ :members:
diff --git a/docs/source/_templates/autosummary/recursive_class.rst b/docs/source/_templates/autosummary/recursive_class.rst
new file mode 100644
index 0000000..4a8af04
--- /dev/null
+++ b/docs/source/_templates/autosummary/recursive_class.rst
@@ -0,0 +1,26 @@
+{% 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 %}
diff --git a/docs/source/api/generation.rst b/docs/source/api/generation.rst
index f15b117..e8aac4a 100644
--- a/docs/source/api/generation.rst
+++ b/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
diff --git a/docs/source/api/index.rst b/docs/source/api/index.rst
deleted file mode 100644
index 1ea987f..0000000
--- a/docs/source/api/index.rst
+++ /dev/null
@@ -1,14 +0,0 @@
-#############
-API Reference
-#############
-
-These pages provide a reference for the public API of *pystencils-sfg*.
-
-.. toctree::
- :maxdepth: 1
-
- generation
- composer
- lang
- ir
- errors
diff --git a/docs/source/conf.py b/docs/source/conf.py
index c9e2cc3..9b56657 100644
--- a/docs/source/conf.py
+++ b/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
diff --git a/docs/source/index.md b/docs/source/index.md
index c65d577..44ef4e8 100644
--- a/docs/source/index.md
+++ b/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
```
[](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*.
+```
diff --git a/docs/source/usage/examples/.gitignore b/docs/source/usage/examples/.gitignore
index 26a5736..97dbcc9 100644
--- a/docs/source/usage/examples/.gitignore
+++ b/docs/source/usage/examples/.gitignore
@@ -1,2 +1,3 @@
*.cpp
-*.h
\ No newline at end of file
+*.h
+*.hpp
\ No newline at end of file
diff --git a/docs/source/usage/index.md b/docs/source/usage/index.md
deleted file mode 100644
index 5783e9e..0000000
--- a/docs/source/usage/index.md
+++ /dev/null
@@ -1,38 +0,0 @@
-# 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*.
-```
diff --git a/src/pystencilssfg/__init__.py b/src/pystencilssfg/__init__.py
index 3bea41f..b2def3b 100644
--- a/src/pystencilssfg/__init__.py
+++ b/src/pystencilssfg/__init__.py
@@ -1,5 +1,5 @@
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",
diff --git a/src/pystencilssfg/config.py b/src/pystencilssfg/config.py
index 8562e0e..aef3e78 100644
--- a/src/pystencilssfg/config.py
+++ b/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."""
--
GitLab