Refactor and Improve Documentation

This MR contributes various refactorings and improvements to the Sphinx documentation of pystencils.

• Delete doc subfolder containing the old documentation tree
• Introduce sphinx-design elements for more pleasing visuals
• Create a welcome page with general information about the project
• Start constructing a comprehensive reference guide and API reference
• Use sphinx.ext.autosummary where appropriate to declutter API listings into several subpages
• Set the build-documentation CI task to fail when errors occur during sphinx-build
• Fix various reference errors in docstrings throughout the project
• Started writing a migration guide for downstream code from 1.3.x. to 2.0

This MR exclusively touches documentation files and docstrings. When reviewing, it might be sensible to focus on the generated doc pages available in the pipeline artifacts.

There is still a lot of work to do to bring the documentation up to standards; this set of changes is by no means complete.

src/pystencils/backend/kernelcreation/iteration_space.py

@@ -193,22 +193,27 @@ class FullIterationSpace(IterationSpace):
 
     @property
     def dimensions(self):
+        """The dimensions of this iteration space"""
         return self._dimensions
 
     @property
     def lower(self):
+        """Lower limits of each dimension"""
         return (dim.start for dim in self._dimensions)
 
     @property
     def upper(self):
+        """Upper limits of each dimension"""
         return (dim.stop for dim in self._dimensions)
 
     @property
     def steps(self):
+        """Iteration steps of each dimension"""
         return (dim.step for dim in self._dimensions)
 
     @property
     def archetype_field(self) -> Field | None:
+        """Field whose shape and memory layout act as archetypes for this iteration space's dimensions."""
         return self._archetype_field
     
     @property
@@ -231,6 +236,13 @@ class FullIterationSpace(IterationSpace):
     def actual_iterations(
         self, dimension: int | FullIterationSpace.Dimension | None = None
     ) -> PsExpression:
+        """Construct an expression representing the actual number of unique points inside the iteration space.
+        
+        Args:
+            dimension: If an integer or a `Dimension` object is given, the number of iterations in that
+                dimension is computed. If `None`, the total number of iterations inside the entire space
+                is computed.
+        """
         from .typification import Typifier
         from ..transformations import EliminateConstants