Merge remote-tracking branch 'upstream/master' into version_tuples

MetOffice · Aug 13, 2024 · 6826c85 · 6826c85
2 parents 02fbb7b + 546ee9e
commit 6826c85
Show file tree

Hide file tree

Showing 47 changed files with 298 additions and 237 deletions.
diff --git a/.github/workflows/build_docs.yml b/.github/workflows/build_docs.yml
diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml
@@ -0,0 +1,56 @@
+name: Build Documentation
+
+on:
+  push:
+    branches:
+      - 'master'
+  workflow_dispatch:
+
+jobs:
+  sphinx-build:
+
+    runs-on: ubuntu-24.04
+
+    steps:
+    - name: Cache Python packages
+      uses: actions/cache@v4
+      with:
+        path: ~/.pip/cache
+        key: ${{ runner.os }}-build-${{ env.cache-name }}-${{ hashFiles('**/pyproject.toml') }}
+
+    - name: Install Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.10'
+
+    - name: Check out Fab source
+      uses: actions/checkout@v4
+
+    - name: Install documentation tools
+      run: pip install .[docs]
+
+    - name: Generate documentation
+      run: |
+        cd Documentation
+        sphinx-apidoc --separate --module-first -d 5 -f -o source/apidoc ../source/fab
+        make html
+
+    - name: Prepare and upload asset
+      uses: actions/upload-pages-artifact@v3
+      with:
+        path: Documentation/build/html
+
+
+  deploy-documentation:
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{steps.deploy-documentation.outputs.page_url}}
+    runs-on: ubuntu-24.04
+    needs: sphinx-build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
diff --git a/docs/Makefile → Documentation/Makefile b/docs/Makefile → Documentation/Makefile
diff --git a/docs/make.bat → Documentation/make.bat b/docs/make.bat → Documentation/make.bat
@@ -1,35 +1,35 @@
-@ECHO OFF
-
-pushd %~dp0
-
-REM Command file for Sphinx documentation
-
-if "%SPHINXBUILD%" == "" (
-	set SPHINXBUILD=sphinx-build
-)
-set SOURCEDIR=source
-set BUILDDIR=build
-
-if "%1" == "" goto help
-
-%SPHINXBUILD% >NUL 2>NUL
-if errorlevel 9009 (
-	echo.
-	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
-	echo.installed, then set the SPHINXBUILD environment variable to point
-	echo.to the full path of the 'sphinx-build' executable. Alternatively you
-	echo.may add the Sphinx directory to PATH.
-	echo.
-	echo.If you don't have Sphinx installed, grab it from
-	echo.https://www.sphinx-doc.org/
-	exit /b 1
-)
-
-%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
-goto end
-
-:help
-%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
-
-:end
-popd
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd
diff --git a/docs/source/_templates/crown-copyright.html → ...on/source/_templates/crown-copyright.html b/docs/source/_templates/crown-copyright.html → ...on/source/_templates/crown-copyright.html
diff --git a/docs/source/advanced_config.rst → Documentation/source/advanced_config.rst b/docs/source/advanced_config.rst → Documentation/source/advanced_config.rst
@@ -254,7 +254,7 @@ in particular where it creates files within it.
                 *.o (compiled object files)
                 *.mod (mod files)
           metrics/
-          my_program.exe
+          my_program
           log.txt
 
 The *project workspace* folder takes its name from the project label passed in to the build configuration.

diff --git a/docs/source/api.rst → Documentation/source/api.rst b/docs/source/api.rst → Documentation/source/api.rst
diff --git a/docs/source/conf.py → Documentation/source/conf.py b/docs/source/conf.py → Documentation/source/conf.py
@@ -12,6 +12,7 @@
 #
 import os
 import sys
+from fab import __version__ as fab_version
 sys.path.insert(0, os.path.abspath('../../source'))
 
 
@@ -22,8 +23,7 @@
 author = 'Fab Team'
 
 # The full version, including alpha/beta/rc tags
-import fab
-release = fab.__version__
+release = fab_version
 
 # The version up to the minor patch, for distinguishing multi-version docs
 version = '.'.join(release.split('.')[:2])

diff --git a/docs/source/config_intro.rst → Documentation/source/config_intro.rst b/docs/source/config_intro.rst → Documentation/source/config_intro.rst
diff --git a/docs/source/development.rst → Documentation/source/development.rst b/docs/source/development.rst → Documentation/source/development.rst
diff --git a/docs/source/environment.rst → Documentation/source/environment.rst b/docs/source/environment.rst → Documentation/source/environment.rst
diff --git a/docs/source/features.rst → Documentation/source/features.rst b/docs/source/features.rst → Documentation/source/features.rst
diff --git a/docs/source/genindex.rst → Documentation/source/genindex.rst b/docs/source/genindex.rst → Documentation/source/genindex.rst
diff --git a/docs/source/glossary.rst → Documentation/source/glossary.rst b/docs/source/glossary.rst → Documentation/source/glossary.rst
@@ -29,7 +29,7 @@ Glossary
         Fab's built-in steps come with sensible defaults so the user doesn't have to write unnecessary config.
 
         As an example, the Fortran preprocessor has a default artefact getter which reads *".F90"* files
-        from the :term:`Artefact Collection` called ``"all_source"``.
+        from the :term:`Artefact Collection` called ``"INITIAL_SOURCE"``.
 
         Artefact getters are derived from :class:`~fab.artefacts.ArtefactsGetter`.
 
@@ -65,7 +65,7 @@ Glossary
         A folder inside the :term:`Fab Workspace`, containing all source and output from a build config.
 
     Root Symbol
-        The name of a Fortran PROGRAM, or ``"main"`` for C code. Fab builds an exe for every root symbol it's given.
+        The name of a Fortran PROGRAM, or ``"main"`` for C code. Fab builds an executable for every root symbol it's given.
 
     Source Tree
         The :class:`~fab.steps.analyse.analyse` step produces a dependency tree of the entire project source.

diff --git a/...source/img/analysis_results_hierarchy.svg → ...source/img/analysis_results_hierarchy.svg b/...source/img/analysis_results_hierarchy.svg → ...source/img/analysis_results_hierarchy.svg
diff --git a/docs/source/img/busby.png → Documentation/source/img/busby.png b/docs/source/img/busby.png → Documentation/source/img/busby.png
diff --git a/docs/source/img/hist.png → Documentation/source/img/hist.png b/docs/source/img/hist.png → Documentation/source/img/hist.png
diff --git a/docs/source/img/pie.png → Documentation/source/img/pie.png b/docs/source/img/pie.png → Documentation/source/img/pie.png
diff --git a/docs/source/img/steps_and_artefacts.svg → ...tation/source/img/steps_and_artefacts.svg b/docs/source/img/steps_and_artefacts.svg → ...tation/source/img/steps_and_artefacts.svg
diff --git a/docs/source/index.rst → Documentation/source/index.rst b/docs/source/index.rst → Documentation/source/index.rst
diff --git a/docs/source/install.rst → Documentation/source/install.rst b/docs/source/install.rst → Documentation/source/install.rst
diff --git a/docs/source/metoffice.rst → Documentation/source/metoffice.rst b/docs/source/metoffice.rst → Documentation/source/metoffice.rst
diff --git a/docs/source/py-modindex.rst → Documentation/source/py-modindex.rst b/docs/source/py-modindex.rst → Documentation/source/py-modindex.rst
diff --git a/docs/source/site-specific-config.rst → ...mentation/source/site-specific-config.rst b/docs/source/site-specific-config.rst → ...mentation/source/site-specific-config.rst
diff --git a/docs/source/writing_config.rst → Documentation/source/writing_config.rst b/docs/source/writing_config.rst → Documentation/source/writing_config.rst
@@ -79,7 +79,7 @@ Please see the documentation for :func:`~fab.steps.find_source_files.find_source
 including how to exclude certain source code from the build. More grab steps can be found in the :mod:`~fab.steps.grab`
 module.
 
-After the find_source_files step, there will be a collection called ``"ALL_SOURCE"``, in the artefact store.
+After the find_source_files step, there will be a collection called ``"INITIAL_SOURCE"``, in the artefact store.
 
 .. [1] See :func:`~fab.steps.c_pragma_injector.c_pragma_injector` for an example of a step which
     creates artefacts in the source folder.
@@ -94,7 +94,7 @@ which must happen before we analyse it.
 
 Steps generally create and find artefacts in the :term:`Artefact Store`, arranged into named collections.
 The :func:`~fab.steps.preprocess.preprocess_fortran`
-automatically looks for Fortran source code in a collection named `'ALL_SOURCE'`,
+automatically looks for Fortran source code in a collection named `'INITIAL_SOURCE'`,
 which is the default output from the preceding :funcfind_source_files step.
 It filters just the (uppercase) ``.F90`` files.
 
@@ -293,8 +293,8 @@ it is the user's responsibility to maintain the default artefact sets
   My apologies for the LONG lines, they were the only way I could find
   to have properly indented paragraphs :(
 
-1. :func:`~fab.steps.find_source_files.find_source_files` will add all source files it finds to ``ALL_SOURCE`` (by default, can be overwritten by the user). Any ``.F90`` and ``.f90`` file will also be added to ``FORTRAN_BUILD_FILES``, any ``.c`` file to ``C_BUILD_FILES``, and any ``.x90`` or ``.X90`` file to ``X90_BUILD_FILES``. It can be called several times if files from different root directories need to be added, and it will automatically update the ``*_BUILD_FILES`` sets.
-2. Any user script that creates new files can add files to ``ALL_SOURCE`` if required, but also to the corresponding ``*_BUILD_FILES``. This will happen automatically if :func:`~fab.steps.find_source_files.find_source_files` is called to add these newly created files.
+1. :func:`~fab.steps.find_source_files.find_source_files` will add all source files it finds to ``INITIAL_SOURCE`` (by default, can be overwritten by the user). Any ``.F90`` and ``.f90`` file will also be added to ``FORTRAN_BUILD_FILES``, any ``.c`` file to ``C_BUILD_FILES``, and any ``.x90`` or ``.X90`` file to ``X90_BUILD_FILES``. It can be called several times if files from different root directories need to be added, and it will automatically update the ``*_BUILD_FILES`` sets.
+2. Any user script that creates new files can add files to ``INITIAL_SOURCE`` if required, but also to the corresponding ``*_BUILD_FILES``. This will happen automatically if :func:`~fab.steps.find_source_files.find_source_files` is called to add these newly created files.
 3. If :func:`~fab.steps.c_pragma_injector.c_pragma_injector` is being called, it will handle all files in ``C_BUILD_FILES``, and will replace all the original C files with the newly created ones. For backward compatibility it will also store the new objects in the ``PRAGMAD_C`` set.
 4. If :func:`~fab.steps.preprocess.preprocess_c` is called, it will preprocess all files in ``C_BUILD_FILES`` (at this stage typically preprocess the files in the original source folder, writing the output files to the build folder), and update that artefact set accordingly. For backward compatibility it will also store the preprocessed files in ``PREPROCESSED_C``.
 5. If :func:`~fab.steps.preprocess.preprocess_fortran` is called, it will preprocess all files in ``FORTRAN_BUILD_FILES`` that end on ``.F90``, creating new ``.f90`` files in the build folder. These files will be added to ``PREPROCESSED_FORTRAN``. Then the original ``.F90`` are removed from ``FORTRAN_BUILD_FILES``, and the new preprocessed files (which are in ``PREPROCESSED_FORTRAN``) will be added. Then any ``.f90`` files that are not already in the build folder (an example of this are files created by a user script) are copied from the original source folder into the build folder, and ``FORTRAN_BUILD_FILES`` is updated to use the files in the new location.

diff --git a/docs/.nojekyll b/docs/.nojekyll
diff --git a/docs/readme b/docs/readme
diff --git a/run_configs/lfric/atm.py b/run_configs/lfric/atm.py
@@ -20,7 +20,7 @@
 from fab.tools import ToolBox
 
 from grab_lfric import lfric_source_config, gpl_utils_source_config
-from lfric_common import (configurator, fparser_workaround_stop_concatenation,
+from lfric_common import (API, configurator, fparser_workaround_stop_concatenation,
                           get_transformation_script)
 
 logger = logging.getLogger('fab')
@@ -247,7 +247,7 @@ def file_filtering(config):
             kernel_roots=[state.build_output / 'lfric' / 'kernel'],
             transformation_script=get_transformation_script,
             cli_args=[],
-            api="dynamo0.3",
+            api=API,
         )
 
         # todo: do we need this one in here?

diff --git a/run_configs/lfric/gungho.py b/run_configs/lfric/gungho.py
@@ -22,7 +22,7 @@
 from fab.tools import ToolBox
 
 from grab_lfric import lfric_source_config, gpl_utils_source_config
-from lfric_common import (configurator, fparser_workaround_stop_concatenation,
+from lfric_common import (API, configurator, fparser_workaround_stop_concatenation,
                           get_transformation_script)
 
 logger = logging.getLogger('fab')
@@ -72,7 +72,7 @@
             kernel_roots=[state.build_output],
             transformation_script=get_transformation_script,
             cli_args=[],
-            api="dynamo0.3",
+            api=API,
         )
 
         fparser_workaround_stop_concatenation(state)

diff --git a/run_configs/lfric/lfric_common.py b/run_configs/lfric/lfric_common.py
@@ -1,15 +1,19 @@
 import logging
 import os
 import shutil
+from typing import Optional
 from pathlib import Path
 
 from fab.artefacts import ArtefactSet
+from fab.build_config import BuildConfig
 from fab.steps import step
 from fab.steps.find_source_files import find_source_files
 from fab.tools import Category, Tool
 
 logger = logging.getLogger('fab')
 
+API = "dynamo0.3"
+
 
 class Script(Tool):
     '''A simple wrapper that runs a shell script.
@@ -111,11 +115,11 @@ def fparser_workaround_stop_concatenation(config):
 
 
 # ============================================================================
-def get_transformation_script(fpath, config):
+def get_transformation_script(fpath: Path,
+                              config: BuildConfig) -> Optional[Path]:
     ''':returns: the transformation script to be used by PSyclone.
-    :rtype: Path
-
     '''
+
     optimisation_path = config.source_root / 'optimisation' / 'meto-spice'
     relative_path = None
     for base_path in [config.source_root, config.build_output]:
@@ -132,4 +136,4 @@ def get_transformation_script(fpath, config):
     global_transformation_script = optimisation_path / 'global.py'
     if global_transformation_script.exists():
         return global_transformation_script
-    return ""
+    return None
diff --git a/run_configs/lfric/mesh_tools.py b/run_configs/lfric/mesh_tools.py
@@ -13,7 +13,7 @@
 from fab.steps.psyclone import psyclone, preprocess_x90
 from fab.tools import ToolBox
 
-from lfric_common import configurator, fparser_workaround_stop_concatenation
+from lfric_common import API, configurator, fparser_workaround_stop_concatenation
 from grab_lfric import lfric_source_config, gpl_utils_source_config
 
 
@@ -57,7 +57,7 @@
             kernel_roots=[state.build_output],
             cli_args=['--config', Path(__file__).parent / 'psyclone.cfg'],
             overrides_folder=state.source_root / 'mesh_tools_overrides',
-            api="dynamo0.3",
+            api=API,
         )
 
         fparser_workaround_stop_concatenation(state)