Skip to content
Snippets Groups Projects
Commit d7843769 authored by Frederik Hennig's avatar Frederik Hennig
Browse files

Refactor documentation

 - update API docs of config system
 - update sidebar toctree with captions
parent bc0bf483
No related branches found
No related tags found
1 merge request!2Refactor Configuration System & Extend Documentation
Pipeline #70689 passed
**/generated
{{ fullname | escape | underline}}
.. currentmodule:: {{ module }}
.. autoclass:: {{ objname }}
:members:
{% 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 %}
...@@ -5,13 +5,26 @@ Generator Script Interface ...@@ -5,13 +5,26 @@ Generator Script Interface
.. autoclass:: pystencilssfg.SourceFileGenerator .. autoclass:: pystencilssfg.SourceFileGenerator
:members: :members:
.. autoclass:: pystencilssfg.SfgConfiguration Configuration
:members: =============
.. autoclass:: pystencilssfg.SfgOutputMode .. module:: pystencilssfg.config
:members:
.. autoclass:: pystencilssfg.SfgCodeStyle .. autoclass:: SfgConfig
:members: :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
#############
API Reference
#############
These pages provide a reference for the public API of *pystencils-sfg*.
.. toctree::
:maxdepth: 1
generation
composer
lang
ir
errors
...@@ -27,6 +27,7 @@ extensions = [ ...@@ -27,6 +27,7 @@ extensions = [
"myst_parser", "myst_parser",
"sphinx.ext.autodoc", "sphinx.ext.autodoc",
"sphinx.ext.napoleon", "sphinx.ext.napoleon",
"sphinx.ext.autosummary",
"sphinx.ext.doctest", "sphinx.ext.doctest",
"sphinx.ext.intersphinx", "sphinx.ext.intersphinx",
"sphinx_autodoc_typehints", "sphinx_autodoc_typehints",
...@@ -71,6 +72,7 @@ intersphinx_mapping = { ...@@ -71,6 +72,7 @@ intersphinx_mapping = {
autodoc_member_order = "bysource" autodoc_member_order = "bysource"
autodoc_typehints = "description" autodoc_typehints = "description"
# autodoc_class_signature = "separated"
# Doctest Setup # Doctest Setup
......
...@@ -3,9 +3,24 @@ ...@@ -3,9 +3,24 @@
```{toctree} ```{toctree}
:maxdepth: 1 :maxdepth: 1
:hidden: :hidden:
:caption: User Guide
usage/index usage/generator_scripts
api/index 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) [![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>`: ...@@ -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 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). [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*.
```
*.cpp *.cpp
*.h *.h
\ No newline at end of file *.hpp
\ No newline at end of file
# 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*.
```
from .config import SfgConfig from .config import SfgConfig
from .generator import SourceFileGenerator from .generator import SourceFileGenerator, GLOBAL_NAMESPACE, OutputMode
from .composer import SfgComposer from .composer import SfgComposer
from .context import SfgContext from .context import SfgContext
from .lang import SfgVar, AugExpr from .lang import SfgVar, AugExpr
...@@ -7,6 +7,8 @@ from .exceptions import SfgException ...@@ -7,6 +7,8 @@ from .exceptions import SfgException
__all__ = [ __all__ = [
"SfgConfig", "SfgConfig",
"GLOBAL_NAMESPACE",
"OutputMode",
"SourceFileGenerator", "SourceFileGenerator",
"SfgComposer", "SfgComposer",
"SfgContext", "SfgContext",
......
...@@ -92,6 +92,8 @@ class ConfigBase(ABC): ...@@ -92,6 +92,8 @@ class ConfigBase(ABC):
@dataclass @dataclass
class FileExtensions(ConfigBase): class FileExtensions(ConfigBase):
"""Option category containing output file extensions."""
header: Option[str] = Option("hpp") header: Option[str] = Option("hpp")
"""File extension for generated header file.""" """File extension for generated header file."""
...@@ -108,6 +110,8 @@ class FileExtensions(ConfigBase): ...@@ -108,6 +110,8 @@ class FileExtensions(ConfigBase):
class OutputMode(Enum): class OutputMode(Enum):
"""Output mode of the source file generator."""
STANDALONE = auto() STANDALONE = auto()
"""Generate a header/implementation file pair (e.g. ``.hpp/.cpp``) where the implementation file will """Generate a header/implementation file pair (e.g. ``.hpp/.cpp``) where the implementation file will
be compiled to a standalone object.""" be compiled to a standalone object."""
...@@ -126,6 +130,8 @@ class OutputMode(Enum): ...@@ -126,6 +130,8 @@ class OutputMode(Enum):
@dataclass @dataclass
class CodeStyle(ConfigBase): class CodeStyle(ConfigBase):
"""Options affecting the code style used by the source file generator."""
indent_width: Option[int] = Option(2) indent_width: Option[int] = Option(2)
"""The number of spaces successively nested blocks should be indented with""" """The number of spaces successively nested blocks should be indented with"""
...@@ -142,6 +148,8 @@ class CodeStyle(ConfigBase): ...@@ -142,6 +148,8 @@ class CodeStyle(ConfigBase):
@dataclass @dataclass
class ClangFormatOptions(ConfigBase): class ClangFormatOptions(ConfigBase):
"""Options affecting the invocation of ``clang-format`` for automatic code formatting."""
code_style: Option[str] = Option("file") code_style: Option[str] = Option("file")
"""Code style to be used by clang-format. Passed verbatim to `--style` argument of the clang-format CLI. """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): ...@@ -150,10 +158,10 @@ class ClangFormatOptions(ConfigBase):
""" """
force: Option[bool] = Option(False) 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) 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") binary: Option[str] = Option("clang-format")
"""Path to the clang-format executable""" """Path to the clang-format executable"""
...@@ -179,25 +187,58 @@ class _GlobalNamespace: ... # noqa: E701 ...@@ -179,25 +187,58 @@ class _GlobalNamespace: ... # noqa: E701
GLOBAL_NAMESPACE = _GlobalNamespace() GLOBAL_NAMESPACE = _GlobalNamespace()
"""Indicates the C++ global namespace."""
@dataclass @dataclass
class SfgConfig(ConfigBase): class SfgConfig(ConfigBase):
"""Configuration options for the `SourceFileGenerator`."""
extensions: FileExtensions = field(default_factory=FileExtensions) 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) 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) outer_namespace: Option[str | _GlobalNamespace] = Option(GLOBAL_NAMESPACE)
"""The outermost namespace in the generated file. May be a valid C++ nested namespace qualifier """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) 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) 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(".") output_directory: Option[str] = Option(".")
"""Directory to which the generated files should be written.""" """Directory to which the generated files should be written."""
......
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment