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

More documentation refactoring; use autosummary where applicable to improve doc readability

parent f664fe7e
No related branches found
No related tags found
1 merge request!425Refactor and Improve Documentation
Pipeline #70155 failed
build build
# sphinx.ext.autosummary generated files # sphinx.ext.autosummary generated files
source/reference/autoapi **/autoapi
table.docutils {
width: 100%;
}
{{ fullname | escape | underline}}
.. currentmodule:: {{ module }}
.. autoclass:: {{ objname }}
:members:
...@@ -17,23 +17,117 @@ Inheritance Diagram ...@@ -17,23 +17,117 @@ Inheritance Diagram
Base Classes Base Classes
------------ ------------
.. automodule:: pystencils.backend.ast.astnode .. module:: pystencils.backend.ast.astnode
:members:
.. autosummary::
:toctree: autoapi
:nosignatures:
:template: autosummary/entire_class.rst
PsAstNode
PsLeafMixIn
Structural Nodes Structural Nodes
---------------- ----------------
.. automodule:: pystencils.backend.ast.structural .. module:: pystencils.backend.ast.structural
:members:
.. autosummary::
:toctree: autoapi
:nosignatures:
:template: autosummary/entire_class.rst
PsBlock
PsStatement
PsAssignment
PsDeclaration
PsLoop
PsConditional
PsEmptyLeafMixIn
PsPragma
PsComment
Expressions Expressions
----------- -----------
.. automodule:: pystencils.backend.ast.expressions .. module:: pystencils.backend.ast.expressions
:members:
.. autosummary::
:toctree: autoapi
:nosignatures:
:template: autosummary/entire_class.rst
PsExpression
PsLvalue
PsSymbolExpr
PsConstantExpr
PsLiteralExpr
PsBufferAcc
PsSubscript
PsMemAcc
PsLookup
PsCall
PsTernary
PsNumericOpTrait
PsIntOpTrait
PsBoolOpTrait
PsUnOp
PsNeg
PsAddressOf
PsCast
PsBinOp
PsAdd
PsSub
PsMul
PsDiv
PsIntDiv
PsRem
PsLeftShift
PsRightShift
PsBitwiseAnd
PsBitwiseXor
PsBitwiseOr
PsAnd
PsOr
PsNot
PsRel
PsEq
PsNe
PsGe
PsLe
PsGt
PsLt
PsArrayInitList
SIMD Nodes SIMD Nodes
---------- ----------
.. automodule:: pystencils.backend.ast.vector .. module:: pystencils.backend.ast.vector
:members:
.. autosummary::
:toctree: autoapi
:nosignatures:
:template: autosummary/entire_class.rst
PsVectorOp
PsVecBroadcast
PsVecMemAcc
Utility
-------
.. currentmodule:: pystencils.backend.ast
.. autosummary::
:toctree: autoapi
:nosignatures:
expressions.evaluate_expression
dfs_preorder
dfs_postorder
util.AstEqWrapper
util.determine_memory_object
...@@ -61,6 +61,9 @@ inheritance_graph_attrs = { ...@@ -61,6 +61,9 @@ inheritance_graph_attrs = {
html_theme = "furo" html_theme = "furo"
html_static_path = ["_static"] html_static_path = ["_static"]
html_css_files = [
'css/fixtables.css',
]
# NbSphinx configuration # NbSphinx configuration
......
...@@ -51,7 +51,7 @@ Code using any of these two should not require any changes, except: ...@@ -51,7 +51,7 @@ Code using any of these two should not require any changes, except:
- *Importing `TypedSymbol` and `create_type`:* Both `TypedSymbol` and `create_type` should now be imported directly - *Importing `TypedSymbol` and `create_type`:* Both `TypedSymbol` and `create_type` should now be imported directly
from the ``pystencils`` namespace. from the ``pystencils`` namespace.
- *Custom data types:* `TypedSymbol` used to accept arbitrary strings as data types. - *Custom data types:* `TypedSymbol` used to accept arbitrary strings as data types.
This is no longer possible; instead, import `pystencils.types.PsCustomType <pystencils.types.types.PsCustomType>` and use it to describe This is no longer possible; instead, import `pystencils.types.PsCustomType` and use it to describe
custom data types unknown to pystencils, as in ``TypedSymbol("xs", PsCustomType("std::vector< int >"))`` custom data types unknown to pystencils, as in ``TypedSymbol("xs", PsCustomType("std::vector< int >"))``
All old data type classes (such as ``BasicType``, ``PointerType``, ``StructType``, etc.) have been removed All old data type classes (such as ``BasicType``, ``PointerType``, ``StructType``, etc.) have been removed
......
...@@ -10,5 +10,5 @@ These pages list the public APIs of pystencils, with advice on how to use them. ...@@ -10,5 +10,5 @@ These pages list the public APIs of pystencils, with advice on how to use them.
:maxdepth: 2 :maxdepth: 2
symbolic_language symbolic_language
kernelcreation/index kernelcreation
types types
.. _page_kernel_creation:
***************
Kernel Creation
***************
Targets
=======
.. module:: pystencils.target
.. autosummary::
:toctree: autoapi
:nosignatures:
:template: autosummary/recursive_class.rst
Target
Configuration
=============
.. module:: pystencils.config
.. autosummary::
:toctree: autoapi
:nosignatures:
:template: autosummary/entire_class.rst
CreateKernelConfig
CpuOptimConfig
OpenMpConfig
VectorizationConfig
GpuIndexingConfig
Creation
========
.. module:: pystencils.kernelcreation
.. autosummary::
:toctree: autoapi
:nosignatures:
create_kernel
Kernel Parameters and Function Objects
======================================
.. module:: pystencils.backend.kernelfunction
.. autosummary::
:toctree: autoapi
:nosignatures:
:template: autosummary/entire_class.rst
KernelParameter
KernelFunction
GpuKernelFunction
.. _page_kernel_creation:
***************
Kernel Creation
***************
The primary interface for creating numerical kernels in pystencils is the function `create_kernel`.
Targets
=======
.. automodule:: pystencils.target
:members:
Configuration
=============
.. automodule:: pystencils.config
:members:
Creation
========
.. autofunction:: pystencils.create_kernel
Kernel Parameters and Function Objects
======================================
.. automodule:: pystencils.backend.kernelfunction
:members:
...@@ -2,16 +2,21 @@ ...@@ -2,16 +2,21 @@
Type System Type System
*********** ***********
.. automodule:: pystencils.types .. module:: pystencils.types
Basic Functions Type Creation and Conversion
------------------------------------- ----------------------------
.. autofunction:: pystencils.types.create_type .. autosummary::
.. autofunction:: pystencils.types.create_numeric_type :toctree: autoapi
.. autofunction:: pystencils.types.constify :nosignatures:
.. autofunction:: pystencils.types.deconstify
create_type
create_numeric_type
UserTypeSpec
constify
deconstify
Data Type Class Hierarchy Data Type Class Hierarchy
...@@ -21,18 +26,59 @@ Data Type Class Hierarchy ...@@ -21,18 +26,59 @@ Data Type Class Hierarchy
:top-classes: pystencils.types.PsType :top-classes: pystencils.types.PsType
:parts: 1 :parts: 1
.. autoclass:: pystencils.types.PsType .. autosummary::
:members: :toctree: autoapi
:nosignatures:
:template: autosummary/entire_class.rst
.. automodule:: pystencils.types.types PsType
:members: PsCustomType
PsStructType
PsDereferencableType
PsPointerType
PsArrayType
PsNumericType
PsScalarType
PsVectorType
PsIntegerType
PsBoolType
PsUnsignedIntegerType
PsSignedIntegerType
PsIeeeFloatType
Data Type Abbreviations Data Type Abbreviations
----------------------- -----------------------
.. automodule:: pystencils.types.quick .. module:: pystencils.types.quick
:members:
The `pystencils.types.quick` module contains aliases of most of the above data type classes,
in order to reduce verbosity of code using the type system.
.. autosummary::
Custom
Scalar
Ptr
Arr
Bool
AnyInt
UInt
Int
SInt
Fp
Exceptions
----------
.. currentmodule:: pystencils.types
.. autosummary::
:toctree: autoapi
:nosignatures:
pystencils.types.PsTypeError
Implementation Details Implementation Details
......
class PsTypeError(Exception): class PsTypeError(Exception):
"""Indicates a type error in the pystencils AST.""" """Indicates an error relating to incorrect usage of a pystencils type."""
...@@ -12,6 +12,7 @@ from .types import ( ...@@ -12,6 +12,7 @@ from .types import (
) )
UserTypeSpec = str | type | np.dtype | PsType UserTypeSpec = str | type | np.dtype | PsType
"""Valid arguments for `create_type`."""
def create_type(type_spec: UserTypeSpec) -> PsType: def create_type(type_spec: UserTypeSpec) -> PsType:
...@@ -21,8 +22,7 @@ def create_type(type_spec: UserTypeSpec) -> PsType: ...@@ -21,8 +22,7 @@ def create_type(type_spec: UserTypeSpec) -> PsType:
The ``type_spec`` argument can be any of the following: The ``type_spec`` argument can be any of the following:
- Strings (`str`): will be parsed as common C types, throwing an exception if that fails. - Strings (`str`): will be parsed as common C types, throwing an exception if that fails.
To construct a `PsCustomType` instead, use the constructor of `PsCustomType` Custom types must be created explicitly using `PsCustomType`.
or its abbreviation `types.quick.Custom`.
- Python builtin data types (instances of `type`): Attempts to interpret Python numeric types like so: - Python builtin data types (instances of `type`): Attempts to interpret Python numeric types like so:
- `int` becomes a signed 64-bit integer - `int` becomes a signed 64-bit integer
- `float` becomes a double-precision IEEE-754 float - `float` becomes a double-precision IEEE-754 float
......
...@@ -15,31 +15,31 @@ from .types import ( ...@@ -15,31 +15,31 @@ from .types import (
) )
Custom = PsCustomType Custom = PsCustomType
"""Custom data types are modelled only by their name.""" """Alias of `PsCustomType`"""
Scalar = PsScalarType Scalar = PsScalarType
"""``Scalar()`` matches any subclass of ``PsScalarType``""" """Alias of `PsScalarType`"""
Ptr = PsPointerType Ptr = PsPointerType
"""``Ptr(t)`` matches ``PsPointerType(base_type=t)``""" """Alias of `PsPointerType`"""
Arr = PsArrayType Arr = PsArrayType
"""``Arr(t, s)`` matches ``PsArrayType(base_type=t, size=s)``""" """Alias of `PsArrayType`"""
Bool = PsBoolType Bool = PsBoolType
"""``Bool()`` matches ``PsBoolType()``""" """Alias of `PsBoolType`"""
AnyInt = PsIntegerType AnyInt = PsIntegerType
"""``AnyInt(width)`` matches both ``PsUnsignedIntegerType(width)`` and ``PsSignedIntegerType(width)``""" """Alias of `PsIntegerType`"""
UInt = PsUnsignedIntegerType UInt = PsUnsignedIntegerType
"""``UInt(width)`` matches ``PsUnsignedIntegerType(width)``""" """Alias of `PsUnsignedIntegerType`"""
Int = PsSignedIntegerType Int = PsSignedIntegerType
"""``Int(width)`` matches ``PsSignedIntegerType(width)``""" """Alias of `PsSignedIntegerType`"""
SInt = PsSignedIntegerType SInt = PsSignedIntegerType
"""``SInt(width)`` matches ``PsSignedIntegerType(width)``""" """Alias of `PsSignedIntegerType`"""
Fp = PsIeeeFloatType Fp = PsIeeeFloatType
"""``Fp(width)`` matches ``PsIeeeFloatType(width)``""" """Alias of `PsIeeeFloatType`"""
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment