Merge branch '297_omp_sentinels' into improve_artefact_workflow

MetOffice · Jul 18, 2024 · 4d41847 · 4d41847
2 parents 538e4da + 7bb451f
commit 4d41847
Show file tree

Hide file tree

Showing 29 changed files with 130 additions and 120 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
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
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
diff --git a/docs/.nojekyll b/docs/.nojekyll
diff --git a/docs/readme b/docs/readme
diff --git a/tests/unit_tests/parse/fortran/test_fortran_analyser.f90 b/tests/unit_tests/parse/fortran/test_fortran_analyser.f90
@@ -20,6 +20,10 @@ END SUBROUTINE internal_sub
     SUBROUTINE openmp_sentinel
 !$ USE compute_chunk_size_mod, ONLY: compute_chunk_size  ! Note OpenMP sentinel
 !$ USE test that is not a sentinel with a use statement inside
+!GCC$ unroll 6
+!DIR$ assume (mod(p, 6) == 0)
+!$omp do
+!$acc parallel copyin (array, scalar).
     END SUBROUTINE openmp_sentinel
 
     INTEGER FUNCTION internal_func()

diff --git a/tests/unit_tests/parse/fortran/test_fortran_analyser.py b/tests/unit_tests/parse/fortran/test_fortran_analyser.py
@@ -18,20 +18,25 @@
 from fab.parse.fortran_common import iter_content
 from fab.tools import ToolBox
 
+'''Tests the Fortran analyser.
+'''
 
 # todo: test function binding
 
 
 @pytest.fixture
-def module_fpath():
+def module_fpath() -> Path:
+    '''Simple fixture that sets the name of the module test file.'''
     return Path(__file__).parent / "test_fortran_analyser.f90"
 
 
 @pytest.fixture
-def module_expected(module_fpath):
+def module_expected(module_fpath) -> AnalysedFortran:
+    '''Returns the expected AnalysedFortran instance for the Fortran
+    test module.'''
     return AnalysedFortran(
         fpath=module_fpath,
-        file_hash=1344519263,
+        file_hash=1757501304,
         module_defs={'foo_mod'},
         symbol_defs={'external_sub', 'external_func', 'foo_mod'},
         module_deps={'bar_mod', 'compute_chunk_size_mod'},
@@ -41,7 +46,7 @@ def module_expected(module_fpath):
     )
 
 
-class Test_Analyser(object):
+class TestAnalyser:
 
     @pytest.fixture
     def fortran_analyser(self, tmp_path):
@@ -53,29 +58,37 @@ def fortran_analyser(self, tmp_path):
     def test_empty_file(self, fortran_analyser):
         # make sure we get back an EmptySourceFile
         with mock.patch('fab.parse.AnalysedFile.save'):
-            analysis, artefact = fortran_analyser.run(fpath=Path(Path(__file__).parent / "empty.f90"))
-        assert type(analysis) is EmptySourceFile
+            analysis, artefact = fortran_analyser.run(
+                fpath=Path(Path(__file__).parent / "empty.f90"))
+        assert isinstance(analysis, EmptySourceFile)
         assert artefact is None
 
-    def test_module_file(self, fortran_analyser, module_fpath, module_expected):
+    def test_module_file(self, fortran_analyser, module_fpath,
+                         module_expected):
         with mock.patch('fab.parse.AnalysedFile.save'):
             analysis, artefact = fortran_analyser.run(fpath=module_fpath)
         assert analysis == module_expected
-        assert artefact == fortran_analyser._config.prebuild_folder / f'test_fortran_analyser.{analysis.file_hash}.an'
+        assert artefact == (fortran_analyser._config.prebuild_folder /
+                            f'test_fortran_analyser.{analysis.file_hash}.an')
 
-    def test_program_file(self, fortran_analyser, module_fpath, module_expected):
+    def test_program_file(self, fortran_analyser, module_fpath,
+                          module_expected):
         # same as test_module_file() but replacing MODULE with PROGRAM
         with NamedTemporaryFile(mode='w+t', suffix='.f90') as tmp_file:
-            tmp_file.write(module_fpath.open().read().replace("MODULE", "PROGRAM"))
+            tmp_file.write(module_fpath.open().read().replace("MODULE",
+                                                              "PROGRAM"))
             tmp_file.flush()
             with mock.patch('fab.parse.AnalysedFile.save'):
-                analysis, artefact = fortran_analyser.run(fpath=Path(tmp_file.name))
+                analysis, artefact = fortran_analyser.run(
+                    fpath=Path(tmp_file.name))
 
             module_expected.fpath = Path(tmp_file.name)
-            module_expected._file_hash = 731743441
+            module_expected._file_hash = 3388519280
             module_expected.program_defs = {'foo_mod'}
             module_expected.module_defs = set()
-            module_expected.symbol_defs.update({'internal_sub', 'openmp_sentinel', 'internal_func'})
+            module_expected.symbol_defs.update({'internal_func',
+                                                'internal_sub',
+                                                'openmp_sentinel'})
 
             assert analysis == module_expected
             assert artefact == fortran_analyser._config.prebuild_folder \
@@ -84,11 +97,13 @@ def test_program_file(self, fortran_analyser, module_fpath, module_expected):
 
 # todo: test more methods!
 
-class Test_process_variable_binding(object):
+class TestProcessVariableBinding:
+    '''This test class tests the variable binding.'''
 
     # todo: define and depend, with and without bind name
 
     def test_define_without_bind_name(self, tmp_path):
+        '''Test usage of bind'''
         fpath = tmp_path / 'temp.f90'
 
         open(fpath, 'wt').write("""
@@ -112,13 +127,15 @@ def test_define_without_bind_name(self, tmp_path):
         tree = f2008_parser(reader)
 
         # find the tree node representing the variable binding
-        var_decl = next(obj for obj in iter_content(tree) if isinstance(obj, Type_Declaration_Stmt))
+        var_decl = next(obj for obj in iter_content(tree)
+                        if isinstance(obj, Type_Declaration_Stmt))
 
         # run our handler
         fpath = Path('foo')
         analysed_file = AnalysedFortran(fpath=fpath, file_hash=0)
         analyser = FortranAnalyser()
-        analyser._process_variable_binding(analysed_file=analysed_file, obj=var_decl)
+        analyser._process_variable_binding(analysed_file=analysed_file,
+                                           obj=var_decl)
 
         assert analysed_file.symbol_defs == {'helloworld', }