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
# 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
Base Classes
------------
.. automodule:: pystencils.backend.ast.astnode
:members:
.. module:: pystencils.backend.ast.astnode
.. autosummary::
:toctree: autoapi
:nosignatures:
:template: autosummary/entire_class.rst
PsAstNode
PsLeafMixIn
Structural Nodes
----------------
.. automodule:: pystencils.backend.ast.structural
:members:
.. module:: pystencils.backend.ast.structural
.. autosummary::
:toctree: autoapi
:nosignatures:
:template: autosummary/entire_class.rst
PsBlock
PsStatement
PsAssignment
PsDeclaration
PsLoop
PsConditional
PsEmptyLeafMixIn
PsPragma
PsComment
Expressions
-----------
.. automodule:: pystencils.backend.ast.expressions
:members:
.. module:: pystencils.backend.ast.expressions
.. 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
----------
.. automodule:: pystencils.backend.ast.vector
:members:
.. module:: pystencils.backend.ast.vector
.. 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 = {
html_theme = "furo"
html_static_path = ["_static"]
html_css_files = [
'css/fixtables.css',
]
# NbSphinx configuration
......
......@@ -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
from the ``pystencils`` namespace.
- *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 >"))``
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.
:maxdepth: 2
symbolic_language
kernelcreation/index
kernelcreation
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 @@
Type System
***********
.. automodule:: pystencils.types
.. module:: pystencils.types
Basic Functions
-------------------------------------
Type Creation and Conversion
----------------------------
.. autofunction:: pystencils.types.create_type
.. autofunction:: pystencils.types.create_numeric_type
.. autofunction:: pystencils.types.constify
.. autofunction:: pystencils.types.deconstify
.. autosummary::
:toctree: autoapi
:nosignatures:
create_type
create_numeric_type
UserTypeSpec
constify
deconstify
Data Type Class Hierarchy
......@@ -21,18 +26,59 @@ Data Type Class Hierarchy
:top-classes: pystencils.types.PsType
:parts: 1
.. autoclass:: pystencils.types.PsType
:members:
.. autosummary::
:toctree: autoapi
:nosignatures:
:template: autosummary/entire_class.rst
.. automodule:: pystencils.types.types
:members:
PsType
PsCustomType
PsStructType
PsDereferencableType
PsPointerType
PsArrayType
PsNumericType
PsScalarType
PsVectorType
PsIntegerType
PsBoolType
PsUnsignedIntegerType
PsSignedIntegerType
PsIeeeFloatType
Data Type Abbreviations
-----------------------
.. automodule:: pystencils.types.quick
:members:
.. module:: pystencils.types.quick
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
......
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 (
)
UserTypeSpec = str | type | np.dtype | PsType
"""Valid arguments for `create_type`."""
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:
- 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`
or its abbreviation `types.quick.Custom`.
Custom types must be created explicitly using `PsCustomType`.
- Python builtin data types (instances of `type`): Attempts to interpret Python numeric types like so:
- `int` becomes a signed 64-bit integer
- `float` becomes a double-precision IEEE-754 float
......
......@@ -15,31 +15,31 @@ from .types import (
)
Custom = PsCustomType
"""Custom data types are modelled only by their name."""
"""Alias of `PsCustomType`"""
Scalar = PsScalarType
"""``Scalar()`` matches any subclass of ``PsScalarType``"""
"""Alias of `PsScalarType`"""
Ptr = PsPointerType
"""``Ptr(t)`` matches ``PsPointerType(base_type=t)``"""
"""Alias of `PsPointerType`"""
Arr = PsArrayType
"""``Arr(t, s)`` matches ``PsArrayType(base_type=t, size=s)``"""
"""Alias of `PsArrayType`"""
Bool = PsBoolType
"""``Bool()`` matches ``PsBoolType()``"""
"""Alias of `PsBoolType`"""
AnyInt = PsIntegerType
"""``AnyInt(width)`` matches both ``PsUnsignedIntegerType(width)`` and ``PsSignedIntegerType(width)``"""
"""Alias of `PsIntegerType`"""
UInt = PsUnsignedIntegerType
"""``UInt(width)`` matches ``PsUnsignedIntegerType(width)``"""
"""Alias of `PsUnsignedIntegerType`"""
Int = PsSignedIntegerType
"""``Int(width)`` matches ``PsSignedIntegerType(width)``"""
"""Alias of `PsSignedIntegerType`"""
SInt = PsSignedIntegerType
"""``SInt(width)`` matches ``PsSignedIntegerType(width)``"""
"""Alias of `PsSignedIntegerType`"""
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