diff --git a/docs/.gitignore b/docs/.gitignore new file mode 100644 index 0000000000000000000000000000000000000000..09b697c6051fd22dc5893980ac87e6a0d978cf50 --- /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 0000000000000000000000000000000000000000..8643ade9ab822e8b1ffebc5f3f7ba96db5d0824f --- /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 0000000000000000000000000000000000000000..4a8af04df02869e7af736e61f79fa9faa607c6c8 --- /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 f15b1170099cfb10c9f333cb6f4540137e162654..e8aac4a38268a55b78f80324c949347a959dd647 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 1ea987fdc32cc22a18c423c970d7bdfd0c8ca0cc..0000000000000000000000000000000000000000 --- 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 c9e2cc3b0f04aa70619b8e10e7e0407c00f0145f..9b56657ed573f5ad16751342bc8663cabd4e9d8d 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 c65d57700d041c31de6b950d7d5b7a703b27d73d..44ef4e852712bbe2eca41d4114d5363e1ea98297 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 26a5736a94d1260044161ac4963b05b3f3407025..97dbcc9ef5b156c49d997a8606b4a3e5ac3b8dd6 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 5783e9ebe71faade1b69dd233595eb8dcb3710ce..0000000000000000000000000000000000000000 --- 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 3bea41febe6e23d9c91537a978212e26c071bc35..b2def3b84ba3eab0706b095878a9c165322c1d8b 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 8562e0ef9ebf1a396ee35bfadeefe4c2e3dc67fd..aef3e78e1ab1488bb4cab3da1e3822e26d2c080e 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."""