From 71810559b9a7e86fc4ed81bfbdb7c10e1eaae3c6 Mon Sep 17 00:00:00 2001
From: Frederik Hennig <frederik.hennig@fau.de>
Date: Fri, 8 Nov 2024 15:30:13 +0100
Subject: [PATCH] More documentation refactoring; use autosummary where
applicable to improve doc readability
---
docs/.gitignore | 2 +-
docs/source/_static/css/fixtables.css | 3 +
.../_templates/autosummary/entire_class.rst | 6 +
docs/source/backend/ast.rst | 110 ++++++++++++++++--
docs/source/conf.py | 3 +
docs/source/migration.rst | 2 +-
docs/source/reference/index.rst | 2 +-
docs/source/reference/kernelcreation.rst | 61 ++++++++++
.../source/reference/kernelcreation/index.rst | 30 -----
docs/source/reference/types.rst | 72 +++++++++---
src/pystencils/types/exception.py | 2 +-
src/pystencils/types/parsing.py | 4 +-
src/pystencils/types/quick.py | 20 ++--
13 files changed, 250 insertions(+), 67 deletions(-)
create mode 100644 docs/source/_static/css/fixtables.css
create mode 100644 docs/source/_templates/autosummary/entire_class.rst
create mode 100644 docs/source/reference/kernelcreation.rst
delete mode 100644 docs/source/reference/kernelcreation/index.rst
diff --git a/docs/.gitignore b/docs/.gitignore
index a5ee0b4af..be765e19a 100644
--- a/docs/.gitignore
+++ b/docs/.gitignore
@@ -1,4 +1,4 @@
build
# sphinx.ext.autosummary generated files
-source/reference/autoapi
+**/autoapi
diff --git a/docs/source/_static/css/fixtables.css b/docs/source/_static/css/fixtables.css
new file mode 100644
index 000000000..3bb5ae2f0
--- /dev/null
+++ b/docs/source/_static/css/fixtables.css
@@ -0,0 +1,3 @@
+table.docutils {
+ width: 100%;
+}
diff --git a/docs/source/_templates/autosummary/entire_class.rst b/docs/source/_templates/autosummary/entire_class.rst
new file mode 100644
index 000000000..8643ade9a
--- /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/backend/ast.rst b/docs/source/backend/ast.rst
index 823ee1d97..84ccb01f3 100644
--- a/docs/source/backend/ast.rst
+++ b/docs/source/backend/ast.rst
@@ -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
diff --git a/docs/source/conf.py b/docs/source/conf.py
index 0ac5f7514..9a4592e2e 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -61,6 +61,9 @@ inheritance_graph_attrs = {
html_theme = "furo"
html_static_path = ["_static"]
+html_css_files = [
+ 'css/fixtables.css',
+]
# NbSphinx configuration
diff --git a/docs/source/migration.rst b/docs/source/migration.rst
index d68900b3d..ea59d8881 100644
--- a/docs/source/migration.rst
+++ b/docs/source/migration.rst
@@ -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
diff --git a/docs/source/reference/index.rst b/docs/source/reference/index.rst
index 32860e917..7da7b5795 100644
--- a/docs/source/reference/index.rst
+++ b/docs/source/reference/index.rst
@@ -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
diff --git a/docs/source/reference/kernelcreation.rst b/docs/source/reference/kernelcreation.rst
new file mode 100644
index 000000000..7ea20d6b6
--- /dev/null
+++ b/docs/source/reference/kernelcreation.rst
@@ -0,0 +1,61 @@
+.. _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
diff --git a/docs/source/reference/kernelcreation/index.rst b/docs/source/reference/kernelcreation/index.rst
deleted file mode 100644
index d86d5104e..000000000
--- a/docs/source/reference/kernelcreation/index.rst
+++ /dev/null
@@ -1,30 +0,0 @@
-.. _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:
diff --git a/docs/source/reference/types.rst b/docs/source/reference/types.rst
index 5a740c058..7b0ef5dc1 100644
--- a/docs/source/reference/types.rst
+++ b/docs/source/reference/types.rst
@@ -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
diff --git a/src/pystencils/types/exception.py b/src/pystencils/types/exception.py
index 9cf7db5af..58997c6cc 100644
--- a/src/pystencils/types/exception.py
+++ b/src/pystencils/types/exception.py
@@ -1,2 +1,2 @@
class PsTypeError(Exception):
- """Indicates a type error in the pystencils AST."""
+ """Indicates an error relating to incorrect usage of a pystencils type."""
diff --git a/src/pystencils/types/parsing.py b/src/pystencils/types/parsing.py
index c7a54d1a0..e398b14e3 100644
--- a/src/pystencils/types/parsing.py
+++ b/src/pystencils/types/parsing.py
@@ -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
diff --git a/src/pystencils/types/quick.py b/src/pystencils/types/quick.py
index 146528c65..1c54b5436 100644
--- a/src/pystencils/types/quick.py
+++ b/src/pystencils/types/quick.py
@@ -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`"""
--
GitLab