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

docs/.gitignore

 build
 
 #   sphinx.ext.autosummary generated files
-source/reference/autoapi
+**/autoapi

docs/source/_static/css/fixtables.css

+table.docutils {
+    width: 100%;
+}

docs/source/_templates/autosummary/entire_class.rst

+{{ fullname | escape | underline}}
+
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ objname }}
+    :members:

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

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
 

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

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

docs/source/reference/kernelcreation.rst

+.. _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

docs/source/reference/kernelcreation/index.rst

-.. _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:

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

src/pystencils/types/exception.py

 class PsTypeError(Exception):
-    """Indicates a type error in the pystencils AST."""
+    """Indicates an error relating to incorrect usage of a pystencils type."""

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

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`"""