From 3e77b5b6035628d8a049daed1918c5a3190c7d2f Mon Sep 17 00:00:00 2001
From: Frederik Hennig <frederik.hennig@fau.de>
Date: Fri, 8 Nov 2024 12:00:39 +0100
Subject: [PATCH] Refactor reference guide: Start introducing autosummary for
improving API doc structure
---
docs/.gitignore | 3 +
.../autosummary/recursive_class.rst | 26 ++++++
.../source/api/symbolic_language/astnodes.rst | 7 --
docs/source/api/symbolic_language/field.rst | 8 --
.../api/symbolic_language/sympyextensions.rst | 18 ----
docs/source/conf.py | 1 +
docs/source/index.rst | 8 +-
docs/source/{api => reference}/index.rst | 2 +-
.../kernelcreation/index.rst | 0
.../symbolic_language.rst} | 91 +++++++++++++++++--
docs/source/{api => reference}/types.rst | 0
src/pystencils/field.py | 8 ++
12 files changed, 126 insertions(+), 46 deletions(-)
create mode 100644 docs/source/_templates/autosummary/recursive_class.rst
delete mode 100644 docs/source/api/symbolic_language/astnodes.rst
delete mode 100644 docs/source/api/symbolic_language/field.rst
delete mode 100644 docs/source/api/symbolic_language/sympyextensions.rst
rename docs/source/{api => reference}/index.rst (88%)
rename docs/source/{api => reference}/kernelcreation/index.rst (100%)
rename docs/source/{api/symbolic_language/index.rst => reference/symbolic_language.rst} (57%)
rename docs/source/{api => reference}/types.rst (100%)
diff --git a/docs/.gitignore b/docs/.gitignore
index 378eac25d..a5ee0b4af 100644
--- a/docs/.gitignore
+++ b/docs/.gitignore
@@ -1 +1,4 @@
build
+
+# sphinx.ext.autosummary generated files
+source/reference/autoapi
diff --git a/docs/source/_templates/autosummary/recursive_class.rst b/docs/source/_templates/autosummary/recursive_class.rst
new file mode 100644
index 000000000..4a8af04df
--- /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/symbolic_language/astnodes.rst b/docs/source/api/symbolic_language/astnodes.rst
deleted file mode 100644
index c3961a32e..000000000
--- a/docs/source/api/symbolic_language/astnodes.rst
+++ /dev/null
@@ -1,7 +0,0 @@
-----------------
-Kernel Structure
-----------------
-
-.. autoclass:: pystencils.AssignmentCollection
- :members:
-
diff --git a/docs/source/api/symbolic_language/field.rst b/docs/source/api/symbolic_language/field.rst
deleted file mode 100644
index 2470dc7c7..000000000
--- a/docs/source/api/symbolic_language/field.rst
+++ /dev/null
@@ -1,8 +0,0 @@
-Fields API (pystencils.field)
-=============================
-
-.. automodule:: pystencils.field
- :members:
-
-.. autoclass:: pystencils.sympyextensions.ConditionalFieldAccess
- :members:
diff --git a/docs/source/api/symbolic_language/sympyextensions.rst b/docs/source/api/symbolic_language/sympyextensions.rst
deleted file mode 100644
index 87e95a3cf..000000000
--- a/docs/source/api/symbolic_language/sympyextensions.rst
+++ /dev/null
@@ -1,18 +0,0 @@
-
-Extensions to SymPy
-===================
-
-.. automodule:: pystencils.sympyextensions
-
-Modelling Data Types
---------------------
-
-.. automodule:: pystencils.sympyextensions.typed_sympy
- :members:
-
-
-Integer Operations
-------------------
-
-.. automodule:: pystencils.sympyextensions.integer_functions
- :members:
diff --git a/docs/source/conf.py b/docs/source/conf.py
index 582fba399..0ac5f7514 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -27,6 +27,7 @@ pygments_style = "sphinx"
extensions = [
"sphinx_design",
"sphinx.ext.autodoc",
+ "sphinx.ext.autosummary",
"sphinx.ext.doctest",
"sphinx.ext.intersphinx",
"sphinx.ext.mathjax",
diff --git a/docs/source/index.rst b/docs/source/index.rst
index baf845a94..bed87efa9 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -6,10 +6,10 @@ pystencils v2.0-dev Documentation
:maxdepth: 1
:hidden:
- tutorials/index.rst
- api/index.rst
- migration.rst
- backend/index.rst
+ tutorials/index
+ reference/index
+ migration
+ backend/index
.. note::
You are currently viewing the documentation pages for the development revision |release|
diff --git a/docs/source/api/index.rst b/docs/source/reference/index.rst
similarity index 88%
rename from docs/source/api/index.rst
rename to docs/source/reference/index.rst
index 2cd4d527d..32860e917 100644
--- a/docs/source/api/index.rst
+++ b/docs/source/reference/index.rst
@@ -9,6 +9,6 @@ These pages list the public APIs of pystencils, with advice on how to use them.
.. toctree::
:maxdepth: 2
- symbolic_language/index
+ symbolic_language
kernelcreation/index
types
diff --git a/docs/source/api/kernelcreation/index.rst b/docs/source/reference/kernelcreation/index.rst
similarity index 100%
rename from docs/source/api/kernelcreation/index.rst
rename to docs/source/reference/kernelcreation/index.rst
diff --git a/docs/source/api/symbolic_language/index.rst b/docs/source/reference/symbolic_language.rst
similarity index 57%
rename from docs/source/api/symbolic_language/index.rst
rename to docs/source/reference/symbolic_language.rst
index a756bfaaa..564eadb6c 100644
--- a/docs/source/api/symbolic_language/index.rst
+++ b/docs/source/reference/symbolic_language.rst
@@ -4,14 +4,6 @@
Symbolic Language
*****************
-.. toctree::
- :maxdepth: 1
- :hidden:
-
- field
- astnodes
- sympyextensions
-
Pystencils allows you to define near-arbitrarily complex numerical kernels in its symbolic
language, which is based on the computer algebra system `SymPy <https://www.sympy.org>`_.
The pystencils code generator is able to parse and translate a large portion of SymPy's
@@ -31,6 +23,89 @@ The most important extension to SymPy brought by pystencils are *fields*.
Fields are a symbolic representation of multidimensional cartesian numerical arrays,
as used in many stencil algorithms.
They are represented by the `Field` class.
+Fields can be created from a textual description using the `fields <pystencils.fields>` function,
+or, more concisely, using the factory methods `Field.create_generic` and `Field.create_fixed_size`.
+It is also possible to create a field representing an existing numpy array,
+including its shape, data type, and memory layout, using `Field.create_from_numpy_array`.
+
+.. autosummary::
+ :toctree: autoapi
+ :nosignatures:
+ :template: autosummary/recursive_class.rst
+
+ pystencils.fields
+ pystencils.Field
+
+
+.. autosummary::
+ :nosignatures:
+
+ pystencils.Field.create_generic
+ pystencils.Field.create_fixed_size
+ pystencils.Field.create_from_numpy_array
+
+
+Assignments and Assignment Collections
+======================================
+
+Pystencils relies heavily on SymPy's `Assignment <sympy.codegen.ast.Assignment>` class.
+Assignments are the fundamental components of pystencils kernels;
+they are used both for assigning expressions to symbols
+and for writing values to fields.
+
+.. py:class:: pystencils.Assignment
+
+ Slightly monkey-patched version of `sympy.codegen.ast.Assignment`.
+
+Assignments are combined and structured inside `assignment collections <pystencils.AssignmentCollection>`.
+An assignment collection contains two separate lists of assignments:
+
+- The **subexpressions** list contains assignments to symbols which can be reused in all subsequent assignments.
+ These are typically used to structure computations into parts
+ by precomputing (common) subexpressions
+- The **main assignments** represent the actual effect of the kernel by storing the computation's results
+ into fields.
+
+.. autosummary::
+ :toctree: autoapi
+ :nosignatures:
+ :template: recursive_class
+
+ pystencils.AssignmentCollection
+
+
+Extensions to SymPy
+===================
+
+Pystencils comes with several extensions to the SymPy symbolic algebra system.
+
+Expression Rewriting
+--------------------
+
+Typed Expressions
+-----------------
+
+When building numerical kernels with pystencils, it might at some point become
+necessary to assert tighter control about the data types of symbols and expressions.
+To achieve this, *pystencils* brings a few tools to the table:
+
+.. autosummary::
+ :toctree: autoapi
+
+ pystencils.DynamicType
+ pystencils.TypedSymbol
+ pystencils.sympyextensions.CastFunc
+
+
+Integer Operations
+------------------
+
+.. autosummary::
+ :toctree: autoapi
+
+ pystencils.sympyextensions.integer_functions.int_div
+ pystencils.sympyextensions.integer_functions.int_rem
+
Restrictions on SymPy Expressions
=================================
diff --git a/docs/source/api/types.rst b/docs/source/reference/types.rst
similarity index 100%
rename from docs/source/api/types.rst
rename to docs/source/reference/types.rst
diff --git a/src/pystencils/field.py b/src/pystencils/field.py
index c813c6154..1449a51a8 100644
--- a/src/pystencils/field.py
+++ b/src/pystencils/field.py
@@ -121,6 +121,14 @@ class Field:
>>> stencil = np.array([[0,0], [0,1], [0,-1]])
>>> src, dst = fields("src(3), dst(3) : double[2D]")
>>> assignments = [Assignment(dst[0,0](i), src[-offset](i)) for i, offset in enumerate(stencil)];
+
+ Args:
+ field_name: something
+ field_type: something
+ dtype: something
+ layout: something
+ shape: something
+ strides: something
"""
@staticmethod
--
GitLab