Docs: Some more fine-tuning and fixing...

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/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/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.
@@ -347,7 +347,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.
     """
@@ -375,7 +375,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.
     """
@@ -433,7 +433,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/tools/files.py

@@ -254,6 +254,7 @@ def write_env_launch_script(here, binary, args):
     This writes a simple script of the form
 
     .. code-block::
+
        source env.sh
        bin/<binary> <args>
        exit $?

loki/tools/util.py

@@ -706,11 +706,11 @@ def stdchannel_redirected(stdchannel, dest_filename):
 
     e.g.:
 
-    ```
-    with stdchannel_redirected(sys.stderr, os.devnull):
-        if compiler.has_function('clock_gettime', libraries=['rt']):
-            libraries.append('rt')
-    ```
+    .. code-block:: python
+
+        with stdchannel_redirected(sys.stderr, os.devnull):
+            if compiler.has_function('clock_gettime', libraries=['rt']):
+                libraries.append('rt')
 
     Source: https://stackoverflow.com/a/17753573
 
@@ -719,11 +719,11 @@ def stdchannel_redirected(stdchannel, dest_filename):
     Additionally, capturing of sys.stdout/sys.stderr needs to be disabled explicitly,
     i.e., use the fixture `capsys` and wrap the above:
 
-    ```
-    with capsys.disabled():
-        with stdchannel_redirected(sys.stdout, 'stdout.log'):
-            function()
-    ```
+    .. code-block:: python
+
+        with capsys.disabled():
+            with stdchannel_redirected(sys.stdout, 'stdout.log'):
+                function()
     """
 
     def try_dup(fd):

loki/transformations/extract.py

@@ -32,7 +32,9 @@ def extract_contained_procedures(procedure):
     3. All procedures are removed from the CONTAINS block of ``procedure``.
 
     As a basic example of this transformation, the Fortran subroutine:
+
     .. code-block::
+
         subroutine outer()
             integer :: y
             integer :: o
@@ -47,8 +49,11 @@ def extract_contained_procedures(procedure):
                o = x + y ! Note, 'y' is "global" here!
             end subroutine inner
         end subroutine outer
+
     is modified to:
+
     .. code-block::
+
         subroutine outer()
             integer :: y
             integer :: o
@@ -57,15 +62,19 @@ def extract_contained_procedures(procedure):
             call inner(o, y) ! 'y' now passed as argument.
             contains
         end subroutine outer
+
     and the (modified) child:
+
     .. code-block::
+
         subroutine inner(o, y)
                integer, intent(inout) :: o
                integer, intent(inout) :: y
                integer :: x
                x = 4
                o = x + y ! Note, 'y' is no longer "global"
         end subroutine inner
+
     is returned.
     """
     new_procedures = []

loki/transformations/inline.py

@@ -229,7 +229,8 @@ def inline_constant_parameters(routine, external_only=True):
     The ``.type.initial`` property is used to derive the replacement
     value,a which means for symbols imported from external modules,
     the parent :any:`Module` needs to be supplied in the
-    ``definitions`` to the constructor when creating :param:`routine`.
+    ``definitions`` to the constructor when creating the
+    :any:`Subroutine`.
 
     Variables that are replaced are also removed from their
     corresponding import statements, with empty import statements

loki/transformations/sanitise.py

@@ -138,24 +138,31 @@ def transform_sequence_association(routine):
     Housekeeping routine to replace scalar syntax when passing arrays as arguments
     For example, a call like
 
-    real :: a(m,n)
+    .. code-block::
 
-    call myroutine(a(i,j))
+        real :: a(m,n)
+
+        call myroutine(a(i,j))
 
     where myroutine looks like
 
-    subroutine myroutine(a)
-        real :: a(5)
-    end subroutine myroutine
+    .. code-block::
+
+        subroutine myroutine(a)
+            real :: a(5)
+        end subroutine myroutine
 
     should be changed to
 
-    call myroutine(a(i:m,j)
+    .. code-block::
+
+        call myroutine(a(i:m,j)
 
     Parameters
     ----------
     routine : :any:`Subroutine`
         The subroutine where calls will be changed
+
     """
 
     #List calls in routine, but make sure we have the called routine definition

loki/transformations/transform_derived_types.py

@@ -41,6 +41,7 @@ class DerivedTypeArgumentsTransformation(Transformation):
     (relevant) derived type arguments by its member variables
 
     .. note::
+
        This transformation requires a Scheduler traversal that
        processes callees before callers.
 
@@ -377,6 +378,7 @@ def expand_derived_type_member(cls, var):
         of this routine on the right:
 
         .. code-block::
+
             var name            | return value (parent_name, expansion, new use)   | remarks
            ---------------------+--------------------------------------------------+------------------------------------
             SOME_VAR            | ('some_var', None, None)                         | No expansion