Docs: Update to links from static doc pages

docs/source/backends.rst

@@ -19,8 +19,8 @@ representation to a string representation in the syntax of the target language.
 
 .. autosummary::
 
-   loki.visitors.pprint.Stringifier
-   loki.visitors.pprint.pprint
+   loki.ir.pprint.Stringifier
+   loki.ir.pprint.pprint
 
 Typically, this includes also a custom mapper for expression trees as a
 subclass of :any:`LokiStringifyMapper`. For convenience, each of these
@@ -50,5 +50,5 @@ Currently, Loki has backends to generate Fortran, C, Python, and Maxeler MaxJ
    compatible with the target language. Adapting the IR to the desired output
    format needs to be done before calling the relevant code generation routine.
    For language transpilation (e.g., Fortran to C), corresponding
-   :doc:`transformations <transformations>` must be applied
+   :doc:`transformations <transform>` must be applied
    (e.g., :any:`FortranCTransformation`).

docs/source/getting_started.rst

@@ -53,11 +53,12 @@ provided for this are:
 Example transformations and current features
 ============================================
 
-Loki is primarily an API and toolbox, requiring developers to create their
-own head scripts to create and invoke source-to-source translation toolchains.
-A small set of transformations considered generic enough are provided by the
-package itself in :mod:`loki.transform`. The majority of more complex transformations
-are collected in a separate Python package that lives under ``transformations``.
+Loki is primarily an API and toolbox, allowing developers to create their
+own head scripts and to create and invoke source-to-source translation toolchains.
+In addition, a set of supported transformations is provided by the
+package itself in :mod:`loki.transformations`. These range from utilities
+that can be used with generic Fortran codes to highly bespoke transformations
+for generating GPU code based on highly model-specific assumptions.
 
 The ``loki_transform.py`` script is provided by the Loki install. The primary
 transformation passes provided by these example transformations are:

docs/source/internal_representation.rst

@@ -259,7 +259,6 @@ Mix-ins
 
 .. autosummary::
 
-   loki.expression.symbols.ExprMetadataMixin
    loki.expression.symbols.StrCompareMixin
 
 Expression modules

docs/source/loki_api.rst

@@ -8,5 +8,4 @@ API reference
 
    loki
    scripts
-   transformations
    lint_rules

docs/source/transform.rst

@@ -105,11 +105,11 @@ side-effects.
 Typically, transformations should be implemented by users to encode the
 transformation pipeline for their individual use-case. However, Loki comes
 with a growing number of built-in transformations that are implemented in
-the :mod:`loki.transform` namespace:
+the :mod:`loki.transformations` namespace:
 
 .. autosummary::
 
-   loki.transform
+   loki.transformations
 
 This includes also a number of tools for common transformation tasks that
 are provided as functions that can be readily used when implementing new
@@ -281,17 +281,17 @@ Other traversal modes may be added in the future.
 
 .. autosummary::
 
-   loki.bulk.scheduler.Scheduler
-   loki.bulk.scheduler.SGraph
-   loki.bulk.scheduler.SFilter
-   loki.bulk.configure.SchedulerConfig
-   loki.bulk.configure.TransformationConfig
-   loki.bulk.configure.ItemConfig
-   loki.bulk.item.Item
-   loki.bulk.item.FileItem
-   loki.bulk.item.ModuleItem
-   loki.bulk.item.ProcedureItem
-   loki.bulk.item.TypeDefItem
-   loki.bulk.item.ProcedureBindingItem
-   loki.bulk.item.InterfaceItem
-   loki.bulk.item.ItemFactory
+   loki.batch.scheduler.Scheduler
+   loki.batch.scheduler.SGraph
+   loki.batch.scheduler.SFilter
+   loki.batch.configure.SchedulerConfig
+   loki.batch.configure.TransformationConfig
+   loki.batch.configure.ItemConfig
+   loki.batch.item.Item
+   loki.batch.item.FileItem
+   loki.batch.item.ModuleItem
+   loki.batch.item.ProcedureItem
+   loki.batch.item.TypeDefItem
+   loki.batch.item.ProcedureBindingItem
+   loki.batch.item.InterfaceItem
+   loki.batch.item.ItemFactory

docs/source/visitors.rst

@@ -46,10 +46,10 @@ for that job with some bespoke variants for specific use cases.
 
 .. autosummary::
 
-   loki.visitors.FindNodes
-   loki.visitors.FindScopes
-   loki.visitors.SequenceFinder
-   loki.visitors.PatternFinder
+   loki.ir.find.FindNodes
+   loki.ir.find.FindScopes
+   loki.ir.find.SequenceFinder
+   loki.ir.find.PatternFinder
 
 A common pattern for using :any:`FindNodes` is the following:
 
@@ -71,10 +71,10 @@ nodes according to a mapper.
 
 .. autosummary::
 
-   loki.visitors.Transformer
-   loki.visitors.NestedTransformer
-   loki.visitors.MaskedTransformer
-   loki.visitors.NestedMaskedTransformer
+   loki.ir.transformer.Transformer
+   loki.ir.transformer.NestedTransformer
+   loki.ir.transformer.MaskedTransformer
+   loki.ir.transformer.NestedMaskedTransformer
 
 :any:`Transformer` is commonly used in conjunction with :any:`FindNodes`, with
 the latter being used to build the mapper for the first. The following example
@@ -107,8 +107,8 @@ pretty-printer for the IR that is useful for debugging.
 
 .. autosummary::
 
-   loki.visitors.pprint.Stringifier
-   loki.visitors.pprint
+   loki.ir.pprint.Stringifier
+   loki.ir.pprint
 
 Implementing new visitors
 -------------------------

loki/__init__.py

@@ -5,6 +5,10 @@
 # granted to it by virtue of its status as an intergovernmental organisation
 # nor does it submit to any jurisdiction.
 
+"""
+The Loki source-to-source translation package for Fortran codes.
+"""
+
 from importlib.metadata import version, PackageNotFoundError
 
 # Import the global configuration map

loki/analyse/__init__.py

@@ -4,5 +4,8 @@
 # In applying this licence, ECMWF does not waive the privileges and immunities
 # granted to it by virtue of its status as an intergovernmental organisation
 # nor does it submit to any jurisdiction.
+"""
+Advanced analysis utilities, such as dataflow analysis functionalities.
+"""
 
 from loki.analyse.analyse_dataflow import *  # noqa

loki/analyse/util_linear_algebra.py

@@ -72,11 +72,12 @@ def yield_one_d_systems(matrix, right_hand_side):
 
     Example
     -------
-    ```python
-    for A, b in yield_one_d_systems(matrix, right_hand_side):
-        # Solve the one-dimensional problem A * x = b
-        solution = solve_one_d_system(A, b)
-    ```
+
+    .. code-block:: python
+
+        for A, b in yield_one_d_systems(matrix, right_hand_side):
+            # Solve the one-dimensional problem A * x = b
+            solution = solve_one_d_system(A, b)
     """
     # yield systems with empty left hand side (A) and non empty right hand side
     mask = np.all(matrix == 0, axis=1)

loki/analyse/util_polyhedron.py

@@ -142,9 +142,11 @@ def lower_bounds(self, index_or_variable, ignore_variables=None):
         Return all lower bounds imposed on a variable.
 
         The lower bounds for the variable `j` are given by the index set:
-        ```
+
+        ``
         L = {i | A_ij < 0, i in {0, ..., d-1}}
-        ```
+        ``
+
         Parameters
         ----------
         index_or_variable : int or str or sym.Array or sym.Scalar
@@ -204,9 +206,10 @@ def upper_bounds(self, index_or_variable, ignore_variables=None):
         Return all upper bounds imposed on a variable.
 
         The upper bounds for the variable `j` are given by the index set:
-        ```
+        ``
         U = {i | A_ij > 0, i in {0, ..., d-1}}
-        ```
+        ``
+
         Parameters
         ----------
         index_or_variable : int or str or sym.Array or sym.Scalar

loki/backend/__init__.py

@@ -4,6 +4,9 @@
 # In applying this licence, ECMWF does not waive the privileges and immunities
 # granted to it by virtue of its status as an intergovernmental organisation
 # nor does it submit to any jurisdiction.
+"""
+Backend classes that convert Loki IR into output code in various languages.
+"""
 
 from loki.backend.fgen import * # noqa
 from loki.backend.cgen import * # noqa

loki/batch/__init__.py

@@ -4,6 +4,15 @@
 # In applying this licence, ECMWF does not waive the privileges and immunities
 # granted to it by virtue of its status as an intergovernmental organisation
 # nor does it submit to any jurisdiction.
+"""
+Batch processing abstraction for processing large source trees with Loki.
+
+This sub-package provides the :any:`Scheduler` class that allows Loki
+transformations to be applied over large source trees. For this it
+provides the basic :any:`Transformation` and :any:`Pipeline` classes
+that provide the core interfaces for batch processing, as well as the
+configuration utilities for large call tree traversals.
+"""
 
 from loki.batch.configure import * # noqa
 from loki.batch.item import * # noqa

loki/batch/configure.py

@@ -38,15 +38,15 @@ class SchedulerConfig:
     routines : dict of dicts or list of dicts
         Dicts with routine-specific options.
     dimensions : dict of dicts or list of dicts
-        Dicts with options to define :any`Dimension` objects.
+        Dicts with options to define :any:`Dimension` objects.
     disable : list of str
         Subroutine names that are entirely disabled and will not be
         added to either the callgraph that we traverse, nor the
         visualisation. These are intended for utility routines that
         pop up in many routines but can be ignored in terms of program
         control flow, like ``flush`` or ``abort``.
     enable_imports : bool
-        Disable the inclusion of module imports as scheduler dependencies.
+       Disable the inclusion of module imports as scheduler dependencies.
     transformation_configs : dict
         Dicts with transformation-specific options
     frontend_args : dict

loki/batch/item.py

@@ -72,7 +72,7 @@ class Item(ItemConfig):
     * :any:`InterfaceItem`: corresponding to :any:`Interface`
     * :any:`TypeDefItem`: corresponding to :any:`TypeDef`
     * :any:`ProcedureBindingItem`: corresponding to the :any:`ProcedureSymbol`
-      that is declared in a :any:`Declaration` in a derived type.
+      that is declared in a :any:`ProcedureDeclaration` in a derived type.
 
     The IR node corresponding to an item can be obtain via the :attr:`ir` property.
 
@@ -1397,7 +1397,7 @@ def get_or_create_module_definitions_from_candidates(self, name, config, module_
             The config object from which the item configuration will be derived
         module_names : list of str, optional
             List of module candidates in which to create the definition items. If not provided,
-            all :any:`ModuleItems` in the cache will be considered.
+            all :any:`ModuleItem` in the cache will be considered.
         only : list of :any:`Item` classes, optional
             Filter the generated items to include only those of the type provided in the list
 

loki/batch/sfilter.py

@@ -36,7 +36,7 @@ class SFilter:
     reverse : bool, optional
         Iterate over the dependency graph in reverse direction
     exclude_ignored : bool, optional
-        Exclude :any:`Item`s that have the ``is_ignored`` property
+        Exclude :any:`Item` objects that have the ``is_ignored`` property
     include_external : bool, optional
         Do not skip :any:`ExternalItem` in the iterator
     """

loki/batch/sgraph.py

@@ -60,7 +60,7 @@ def from_seed(cls, seed, item_factory, config=None):
 
     def as_filegraph(self, item_factory, config=None, item_filter=None, exclude_ignored=False):
         """
-        Convert the :any:`Sgraph` to a dependency graph that only contains
+        Convert the :any:`SGraph` to a dependency graph that only contains
         :any:`FileItem` nodes.
 
         Parameters

loki/build/__init__.py

@@ -4,6 +4,13 @@
 # In applying this licence, ECMWF does not waive the privileges and immunities
 # granted to it by virtue of its status as an intergovernmental organisation
 # nor does it submit to any jurisdiction.
+"""
+Just-in-Time compilation utilities used in the Loki test base.
+
+These allow compilation and wrapping of generated Fortran source code
+using `f90wrap <https://github.com/jameskermode/f90wrap>`_ for
+execution from Python tests.
+"""
 
 from loki.logging import * # noqa
 

loki/expression/__init__.py

@@ -4,6 +4,10 @@
 # In applying this licence, ECMWF does not waive the privileges and immunities
 # granted to it by virtue of its status as an intergovernmental organisation
 # nor does it submit to any jurisdiction.
+"""
+Expression layer of the two-level Loki IR based on `Pymbolic
+<https://github.com/inducer/pymbolic>`_.
+"""
 
 from loki.expression.expr_visitors import *  # noqa
 from loki.expression.symbols import *  # noqa

loki/frontend/__init__.py

@@ -4,6 +4,13 @@
 # In applying this licence, ECMWF does not waive the privileges and immunities
 # granted to it by virtue of its status as an intergovernmental organisation
 # nor does it submit to any jurisdiction.
+"""
+Frontend parsers that create Loki IR from input Fortran code.
+
+This includes code sanitisation utilities and several frontend parser
+interfaces, including the REGEX-frontend that is used for fast source
+code exploration in large call and dependency trees.
+"""
 
 from loki.frontend.preprocessing import *  # noqa
 from loki.frontend.source import *  # noqa

loki/ir/__init__.py

@@ -5,6 +5,10 @@
 # granted to it by virtue of its status as an intergovernmental organisation
 # nor does it submit to any jurisdiction.
 
+"""
+The Loki internal representation (IR) and associated APIs for tree traversal.
+"""
+
 from loki.ir.find import *  # noqa
 from loki.ir.ir_graph import *  # noqa
 from loki.ir.nodes import *  # noqa

loki/ir/nodes.py

@@ -63,14 +63,14 @@ class Node:
     metadata.
 
     Attributes
-    -----------
+    ----------
     traversable : list of str
         The traversable fields of the Node; that is, fields walked over by
         a :any:`Visitor`. All arguments in :py:meth:`__init__` whose
         name appear in this list are treated as traversable fields.
 
     Parameters
-    -----------
+    ----------
     source : :any:`Source`, optional
         the information about the original source for the Node.
     label : str, optional

loki/ir/pragma_utils.py

@@ -33,7 +33,7 @@ def is_loki_pragma(pragma, starts_with=None):
 
     Parameters
     ----------
-    pragma : :any:`Pragma` or `list`/`tuple` of `ir.Pragma` or `None`
+    pragma : :any:`Pragma` or `list`/`tuple` of :any:`Pragma` or `None`
         the pragma or list of pragmas to check.
     starts_with : str, optional
         the keyword the pragma content must start with.
@@ -349,7 +349,7 @@ def attach_pragmas(ir, node_type, attach_pragma_post=True):
         the root of (a section of the) intermediate representation in which
         pragmas are to be attached.
     node_type : list
-        the (list of) :any:`ir.Node` types pragmas should be attached to.
+        the (list of) :any:`Node` types pragmas should be attached to.
     attach_pragma_post : bool, optional
         process ``pragma_post`` attachments.
     """
@@ -377,7 +377,7 @@ def detach_pragmas(ir, node_type, detach_pragma_post=True):
         the root node of the (section of the) intermediate representation
         in which pragmas are to be detached.
     node_type :
-        the (list of) :any:`ir.Node` types that pragmas should be detached from.
+        the (list of) :any:`Node` types that pragmas should be detached from.
     detach_pragma_post: bool, optional
         process ``pragma_post`` attachments.
     """
@@ -435,7 +435,7 @@ def pragmas_attached(module_or_routine, node_type, attach_pragma_post=True):
     module_or_routine : :any:`Module` or :any:`Subroutine`
         the program unit in which pragmas are to be inlined.
     node_type :
-        the (list of) :any:`ir.Node` types, that pragmas should be
+        the (list of) :any:`Node` types, that pragmas should be
         attached to.
     attach_pragma_post : bool, optional
         process ``pragma_post`` attachments.

loki/lint/__init__.py

@@ -4,6 +4,9 @@
 # In applying this licence, ECMWF does not waive the privileges and immunities
 # granted to it by virtue of its status as an intergovernmental organisation
 # nor does it submit to any jurisdiction.
+"""
+Code linting infrastructure to allow coding standard checks using Loki.
+"""
 
 from loki.lint.utils import * # noqa
 from loki.lint.rules import * # noqa