#2543 Improve the documentation and fix other typos

.github/workflows/python-package.yml

@@ -66,7 +66,7 @@ jobs:
     - run: sudo apt-get install -y graphviz doxygen
     - run: python -m pip install --upgrade pip
     - run: pip install .[doc]
-    # First we need a first build and launching a server, otherwise the
+    # First we need to build the docs and launch a server, otherwise the
     # intershpinx links would be broken
     - run: cd doc/user_guide; make html
     - run: cd doc/developer_guide; make html
@@ -76,7 +76,7 @@ jobs:
     # Now we can check for warnings and broken links
     - run: cd doc/user_guide; make html SPHINXOPTS="-W --keep-going"
     - run: cd doc/developer_guide; make html SPHINXOPTS="-W --keep-going"
-    # - run: cd doc/reference_guide; make html
+    # TODO #1280: - run: cd doc/reference_guide; make html SPHINXOPTS="-W --keep-going"
     - run: cd doc/psyad/user_guide; make html SPHINXOPTS="-W --keep-going"
     - run: cd doc/user_guide; make linkcheck
     - run: cd doc/developer_guide; make linkcheck

doc/user_guide/getting_going.rst

@@ -47,11 +47,12 @@ Installation
 The following instructions are intended for a PSyclone user who wants
 to work with a released version of the code. If you are a developer or
 wish to test a specific branch of PSyclone from the GitHub repository
-please see :ref:`Installation section in the Developer Guide <dev-installation>`.
+please see the
+:ref:`Installation section in the Developer Guide <dev-installation>`.
 
 .. tabs::
 
-  .. tab:: from PyPI
+  .. tab:: From PyPI:
 
     For a system-wide installation use:
 
@@ -73,10 +74,10 @@ please see :ref:`Installation section in the Developer Guide <dev-installation>`
 
 
     For more information about using ``pip`` or encapsulating the installation
-    in its own ``virtual environment`` we recomment reading the
+    in its own ``virtual environment`` we recommend reading the
     `Python Packaging User Guide <https://packaging.python.org/en/latest/tutorials/installing-packages/>`_.
 
-  .. tab:: from Spack
+  .. tab:: From Spack:
 
     To install psyclone to your loaded Spack installation use:
 
@@ -85,10 +86,10 @@ please see :ref:`Installation section in the Developer Guide <dev-installation>`
       spack install psyclone
 
 
-    For more information about how to use Spack we recommend readign the
+    For more information about how to use Spack we recommend reading the
     `Spack documentation <https://spack-tutorial.readthedocs.io/>`_.
 
-  .. tab:: from Source
+  .. tab:: From Source:
 
     To download and install a specific PSyclone release (where ``X.Y.Z`` is the release version)
     from source, use:
@@ -106,8 +107,8 @@ please see :ref:`Installation section in the Developer Guide <dev-installation>`
 Installation location
 ^^^^^^^^^^^^^^^^^^^^^
 
-PSyclone installation location will vary depending on the specific installation
-method and options used. The ``pyclone`` command will typically already be
+The PSyclone installation location will vary depending on the specific installation
+method and options used. The ``psyclone`` command will typically already be
 prepended to your ``PATH`` after following the instructions above, but sometimes
 you will need to source the virtual environment or load the Spack module again
 after restarting your terminal.
@@ -125,20 +126,20 @@ directory relative to the psyclone installation. You can replace
 Configuration
 -------------
 
-Various aspects of PSyclone are configured through a configuration
+Various aspects of PSyclone are controlled through a configuration
 file, ``psyclone.cfg``.  The default version of this file is located in
 the ``share/psyclone/psyclone.cfg`` file in the :ref:`getting-going-install-loc`.
 
 .. warning::
 
-   If PSyclone is installed in 'editable' mode (``-e`` flag to ``pip``), ``pip``
+   If PSyclone is installed in 'editable' mode (``-e`` flag to ``pip``),
    or in a non-standard location, then PSyclone will not be able to find the
    default configuration file. There are two solutions to this:
 
    1. copy a configuration file to the location specified above.
 
-   2. set the ``PSYCLONE_CONFIG`` environment variable to the full-path to
-   the configuration file, e.g.:
+   2. set the ``PSYCLONE_CONFIG`` environment variable (or the ``--config``
+   flag) to the full-path to the configuration file, e.g.:
 
    .. code-block:: bash
 
@@ -212,7 +213,7 @@ There is more detailed information about each flag in :ref:`psyclone_command` se
 but the main parameters are the input source file that we aim to transform, and a transformation
 recipe that is provided with the ``-s`` flag.
 In addition to these, note that psyclone can be used in two distinct modes:
-the code-transformation mode (when no ``-api``/``--psykal-dsl`` flags is provided) or the
+the code-transformation mode (when no ``-api``/``--psykal-dsl`` flags are provided) or the
 PSyKAl DSL mode (when a ``-api``/``--psykal-dsl`` flag is provided). The following sections provide
 a brief introduction to each mode.
 

doc/user_guide/transformations.rst

@@ -134,8 +134,9 @@ can be found in the API-specific sections).
 .. note:: PSyclone currently only supports OpenCL and
           KernelImportsToArguments transformations for the GOcean 1.0
           API, the OpenACC Data transformation is limited to
-          the NEMO and GOcean 1.0 APIs and the OpenACC Kernels
-          transformation is limited to the NEMO and LFRic (Dynamo0.3) APIs.
+          the generic code transformation and the GOcean 1.0 API and the
+          OpenACC Kernels transformation is limited to the generic code
+          transformation and the LFRic API.
 
 .. note:: The directory layout of PSyclone is currently being restructured.
           As a result of this some transformations are already in the new
@@ -1049,9 +1050,9 @@ As well as ensuring the correct data is copied to and from the remote
 device, OpenACC directives must also be added to a code in order to
 tell the compiler how it should be parallelised. PSyclone provides the
 ``ACCKernelsTrans``, ``ACCParallelTrans`` and ``ACCLoopTrans``
-transformations for this purpose. The simplest of these is
-``ACCKernelsTrans`` (currently only supported for the NEMO and
-Dynamo0.3 APIs) which encloses the code represented by a sub-tree of
+transformations for this purpose. The simplest of these is ``ACCKernelsTrans``
+(currently only supported for the generic code transformation
+and LFRic API) which encloses the code represented by a sub-tree of
 the PSyIR within an OpenACC ``kernels`` region.  This essentially
 gives free-reign to the compiler to automatically parallelise any
 suitable loops within the specified region. An example of the use of
@@ -1085,8 +1086,8 @@ SIR
 
 It is currently not possible for PSyclone to output SIR code without
 using a script. Three examples of such scripts are given in example 4
-for the NEMO API. The first `sir_trans.py` simply outputs SIR. This
-will raise an exception if used with the `tracer advection` example as
+for the NEMO examples directory. The first `sir_trans.py` simply outputs SIR.
+This will raise an exception if used with the `tracer advection` example as
 the example contains array-index notation which is not supported by
 the SIR backend, but will generate code for the other examples. The
 second, `sir_trans_loop.py` includes transformations to hoist code out

doc/user_guide/tutorials_and_examples.rst

@@ -46,16 +46,16 @@ Tutorial
 
 PSyclone provides a hands-on tutorial. The easiest way to follow it is reading
 the `Readme files in github <https://github.com/stfc/PSyclone/tree/master/tutorial/practicals>`_.
-The tutorial is divided in two sections, a first section that introduces
+The tutorial is divided into two sections, a first section that introduces
 PSyclone and how to
 `use it to transform generic Fortran code  <https://github.com/stfc/PSyclone/tree/master/tutorial/practicals/generic>`_
 (this is the recommended starting point for everybody).
-And a second sections about
+And a second section about
 `the LFRic DSL <https://github.com/stfc/PSyclone/tree/master/tutorial/practicals/LFRic>`_
-(this is only recommended for people interested in PSKAL DSLs and LFRic in particular).
+(this is only recommended for people interested in PSyKAL DSLs and LFRic in particular).
 
 To do the proposed hands-on you will need a linux shell with Python installed and to
-download the hand-on directory with:
+download the hands-on directory with:
 
 .. code-block:: bash
 
@@ -765,9 +765,8 @@ Demonstrates the introduction of simple OpenACC parallelisation (using the
 Example 4: Transforming Fortran code to the SIR
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Demonstrates that simple Fortran code examples which conform to the
-NEMO API can be transformed to the Stencil Intermediate Representation
-(SIR). The SIR is the front-end language to DAWN
+Demonstrates that simple Fortran code can be transformed to the Stencil
+Intermediate Representation (SIR). The SIR is the front-end language to DAWN
 (https://github.com/MeteoSwiss-APN/dawn), a tool which generates
 optimised cuda, or gridtools code. Thus various simple Fortran
 examples and the computational part of the tracer-advection benchmark
@@ -778,7 +777,7 @@ Example 5: Kernel Data Extraction
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 This example shows the use of kernel data extraction in PSyclone for
-the NEMO API. It instruments each kernel in the NEMO tracer-advection
+generic Fortran code. It instruments each kernel in the NEMO tracer-advection
 benchmark with the PSyData-based kernel extraction code. Detailed
 compilation instructions are in the ``README.md`` file, including how
 to switch from using the stand-alone extraction library to the NetCDF-based
@@ -797,6 +796,6 @@ adds the largest possible OpenACC Kernels regions to the code being processed.
 
 For more details see the ``examples/nemo/README.md`` file.
 
-Note that these scripts are here to support the ongoing development of the
-NEMO API in PSyclone. They are *not* intended as 'turn-key' solutions but
-as a starting point.
+Note that these scripts are here to support the ongoing development of PSyclone
+to transform the NEMO source. They are *not* intended as 'turn-key' solutions
+but as a starting point.

src/psyclone/tests/conftest.py

@@ -78,9 +78,9 @@ def pytest_addoption(parser):
 
 @pytest.fixture
 def have_graphviz():
-    ''' Whether or not the system has graphviz installed. Note that this
-    only checks for the Python bindings. The underlying library must
-    also have been installed for dag generation to work correctly. '''
+    ''' Whether or not the system has graphviz installed. This refers to
+    the underlying system library, not the python bindings that are provided
+    by 'import graphviz'. '''
     # pylint: disable=import-outside-toplevel
     import graphviz
     try:

tutorial/practicals/generic/Makefile

@@ -32,8 +32,10 @@
 # POSSIBILITY OF SUCH DAMAGE.
 # ------------------------------------------------------------------------------
 # Author: A. R. Porter, STFC Daresbury Lab
+# Modified: S. Siso, STFC Daresbury Lab
 
-# Top-level Makefile to test all of the NEMO hands-on tutorials.
+# Top-level Makefile to test all the hands-on tutorials for transforming
+# generic code.
 
 TUTORIALS = $(sort $(dir $(wildcard */)))