Docs: Add sub-pacakge docstrings

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/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 :and:`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/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 used for fast source
+code exploration in large call 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/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

loki/logging.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.
+"""
+Loki's logger classes and logging utilities.
+"""
 
 import logging
 import sys

loki/tools/__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.
+"""
+Collection of tools and utility methods used throughout Loki.
+"""
 
 from loki.tools.util import *  # noqa
 from loki.tools.files import *  # noqa

loki/transformations/__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.
+"""
+Sub-package with supported source code transformation passes.
+
+This sub-package includes general source code trnasformations and
+bespoke :any:`Transformation` and :any:`Pipeline` classes for
+IFS-specific source-to-source recipes that target GPUs.
+"""
 
 from loki.transformations.array_indexing import * # noqa
 from loki.transformations.build_system import * # noqa

scripts/__init__.py

@@ -0,0 +1,10 @@
+# (C) Copyright 2018- ECMWF.
+# This software is licensed under the terms of the Apache Licence Version 2.0
+# which can be obtained at http://www.apache.org/licenses/LICENSE-2.0.
+# 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.
+
+"""
+Standalone scripts that provide the top-level entry-point to the Loki API.
+"""