Merge branch 'master' into replace-flags-function

.github/workflows/build.yml

@@ -12,9 +12,9 @@ jobs:
         python-version: ['3.7', '3.8', '3.9', '3.10']
 
     steps:
-    - uses: actions/checkout@v1
+    - uses: actions/checkout@v4
     - name: Set up Python ${{ matrix.python-version }}
-      uses: actions/setup-python@v1
+      uses: actions/setup-python@v4
       with:
         python-version: ${{ matrix.python-version }}
     - name: Setup Compiler

docs/source/_templates/crown-copyright.html

@@ -0,0 +1,11 @@
+{# Crown copyright is displayed differently to normal. #}
+{# Configured from conf.py as per usual. #}
+{% if show_copyright and copyright %}
+<p class="copyright">
+    {% if hasdoc('copyright') %}
+    {% trans path=pathto('copyright'), copyright=copyright|e %}© <a href="{{ path }}">Copyright</a> {{ copyright }}.{% endtrans %}
+    {% else %}
+    {% trans copyright=copyright|e %}© Crown Copyright {{ copyright }}.{% endtrans %}
+    {% endif %}
+</p>
+{% endif %}

docs/source/advanced_config.rst

@@ -82,18 +82,22 @@ import your grab configuration to find out where it put the source.
 
     if __name__ == '__main__':
         with BuildConfig(project_label='<project_label>') as state:
-            grab_folder(state, src=grab_config.source_root),
+            grab_folder(state, src=my_grab_config.source_root),
 
 
 Housekeeping
 ============
 
-Fab will remove old files from the prebuilds folder. It will remove all prebuild files that are not part of the current build by default.
+You can add a :func:`~fab.steps.cleanup_prebuilds.cleanup_prebuilds`
+step, where you can explicitly control how long to keep prebuild files.
+This may be useful, for example, if you often switch between two versions
+of your code and want to keep the prebuild speed benefits when building
+both.
 
-If you add a :func:`~fab.steps.cleanup_prebuilds.cleanup_prebuilds` step, you
-can keep prebuild files for longer. This may be useful, for example, if you
-often switch between two versions of your code and want to keep the prebuild
-speed benefits when building both.
+If you do not add your own cleanup_prebuild step, Fab will
+automatically run a default step which will remove old files from the
+prebuilds folder. It will remove all prebuild files that are not part of
+the current build by default.
 
 
 Sharing Prebuilds

docs/source/api.rst

@@ -0,0 +1,10 @@
+API Documentation
+=================
+
+This API documentation is generated from comments within the source code.
+
+.. autosummary::
+   :toctree: api
+   :recursive:
+
+   fab

docs/source/conf.py

@@ -17,8 +17,8 @@
 
 # -- Project information -----------------------------------------------------
 
-project = 'fab'
-copyright = '2023'
+project = 'Fab'
+copyright = '2024 Met Office. All rights reserved.'
 author = 'Fab Team'
 
 # The full version, including alpha/beta/rc tags
@@ -52,24 +52,35 @@
 exclude_patterns = []
 
 
-# -- Options for HTML output -------------------------------------------------
+# -- Autodoc -----------------------------------------------------------------
 
-# The theme to use for HTML and HTML Help pages.  See the documentation for
-# a list of builtin themes.
-#
+autodoc_default_options = {
+    'members': True,
+    'show-inheritane': True
+}
 
-# ugly
-# html_theme = "classic"
+autoclass_content = 'both'
 
-# poor contrast between title, h1 & h2
-# html_theme = "sphinxdoc"
-# html_theme = "sphinx_rtd_theme"
-# html_theme = 'python_docs_theme'
 
-# good contrast between title, h1 & h2
-# html_theme = 'alabaster'
-html_theme = 'sphinx_material'
+# -- Options for HTML output -------------------------------------------------
 
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = 'pydata_sphinx_theme'
+
+html_theme_options = {
+    "icon_links": [
+        {
+            "name": "GitHub",
+            "url": "https://github.com/metomi/fab",
+            "icon": "fa-brands fa-github"
+        }
+    ],
+    "footer_start": ["crown-copyright"],
+    "footer_center": ["sphinx-version"],
+    "footer_end": ["theme-version"],
+}
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
@@ -93,12 +104,3 @@
 
 # include default values in argument descriptions
 typehints_defaults = 'braces-after'
-
-# needed when using material theme
-html_sidebars = {
-    "**": ["logo-text.html", "globaltoc.html", "localtoc.html", "searchbox.html"]
-}
-# needed when not using material theme
-# html_sidebars = {
-#     "**": ["globaltoc.html", "searchbox.html"]
-# }

docs/source/environment.rst

@@ -3,11 +3,11 @@
 Environment
 ***********
 
-Fab requires a suitible Python environment in which to run. This page outlines
+Fab requires a suitable Python environment in which to run. This page outlines
 some routes to achieving such an environment.
 
 This page contains general instructions, there are additional instructions for
-:ref:`Met Office<MetOffice>` users elsewhere.
+:ref:`Met Office<MetOfficeUsage>` users elsewhere.
 
 
 .. _Requirements:

docs/source/index.rst

@@ -81,7 +81,7 @@ See also
    writing_config
    advanced_config
    features
-   Api Reference <apidoc/modules>
+   Api Reference <api>
    development
    glossary
    genindex

docs/source/writing_config.rst

@@ -236,14 +236,14 @@ However preprocessing C currently requires a preceding step called the
 into the C code so Fab is able to deduce which inclusions are user code and
 which are system code. This allows system dependencies to be ignored.
 
-See also :ref:`Advanced C Code<Advanced C Code>`
+See also :ref:`Advanced C Code<C Pragma Injector>`
 
 
 Further Reading
 ===============
 
 More advanced configuration topics are discussed in
-:ref:`Advanced Configuration`.
+:ref:`Advanced Config`.
 
 You can see more complicated configurations in the
 `developer testing directory <https://github.com/metomi/fab/tree/master/run_configs>`_.

pyproject.toml

@@ -22,8 +22,11 @@ classifiers = [
 c-language = ['python-clang']
 plots = ['matplotlib']
 tests = ['pytest', 'pytest-cov', 'pytest-mock']
-checks = ['flake8', 'mypy']
-docs = ['sphinx', 'sphinx-material', 'sphinx-autodoc-typehints', 'sphinx-copybutton']
+checks = ['flake8>=5.0.4', 'mypy']
+docs = ['sphinx',
+        'pydata-sphinx-theme>=0.13.3',
+        'sphinx-autodoc-typehints',
+        'sphinx-copybutton']
 dev = ['sci-fab[plots, tests, checks, docs]']
 
 [project.scripts]

source/fab/steps/compile_fortran.py

@@ -67,7 +67,7 @@ def compile_fortran(config: BuildConfig, common_flags: Optional[List[str]] = Non
         A list of :class:`~fab.build_config.AddFlags`, defining flags to be included in the command line call
         for selected files.
     :param source:
-        An :class:`~fab.artefacts.ArtefactsGetter` which give us our c files to process.
+        An :class:`~fab.artefacts.ArtefactsGetter` which gives us our Fortran files to process.
 
     """
 

source/fab/steps/grab/__init__.py

@@ -24,5 +24,5 @@ def call_rsync(src: Union[str, Path], dst: Union[str, Path]):
     if not src.endswith('/'):
         src += '/'
 
-    command = ['rsync', '--times', '--stats', '-ru', src, str(dst)]
+    command = ['rsync', '--times', '--links', '--stats', '-ru', src, str(dst)]
     return run_command(command)

tests/system_tests/CFortranInterop/test_CFortranInterop.py

@@ -17,14 +17,16 @@
 from fab.steps.link import link_exe
 from fab.steps.preprocess import preprocess_fortran, preprocess_c
 
+import pytest
 
 PROJECT_SOURCE = Path(__file__).parent / 'project-source'
 
 
 def test_CFortranInterop(tmp_path):
 
     # build
-    with BuildConfig(fab_workspace=tmp_path, project_label='foo', multiprocessing=False) as config:
+    with BuildConfig(fab_workspace=tmp_path, project_label='foo', multiprocessing=False) as config, \
+         pytest.warns(UserWarning, match="removing managed flag"):
 
         grab_folder(config, src=PROJECT_SOURCE),
         find_source_files(config),

tests/system_tests/FortranDependencies/test_FortranDependencies.py

@@ -17,11 +17,14 @@
 from fab.steps.link import link_exe
 from fab.steps.preprocess import preprocess_fortran
 
+import pytest
+
 
 def test_FortranDependencies(tmp_path):
 
     # build
-    with BuildConfig(fab_workspace=tmp_path, project_label='foo', multiprocessing=False) as config:
+    with BuildConfig(fab_workspace=tmp_path, project_label='foo', multiprocessing=False) as config, \
+         pytest.warns(UserWarning, match="removing managed flag"):
         grab_folder(config, src=Path(__file__).parent / 'project-source'),
         find_source_files(config),
         preprocess_fortran(config),  # nothing to preprocess, actually, it's all little f90 files

tests/system_tests/FortranPreProcess/test_FortranPreProcess.py

@@ -15,9 +15,12 @@
 from fab.steps.link import link_exe
 from fab.steps.preprocess import preprocess_fortran
 
+import pytest
+
 
 def build(fab_workspace, fpp_flags=None):
-    with BuildConfig(fab_workspace=fab_workspace, project_label='foo', multiprocessing=False) as config:
+    with BuildConfig(fab_workspace=fab_workspace, project_label='foo', multiprocessing=False) as config, \
+         pytest.warns(UserWarning, match="removing managed flag"):
         grab_folder(config, Path(__file__).parent / 'project-source'),
         find_source_files(config),
         preprocess_fortran(config, common_flags=fpp_flags),

tests/system_tests/MinimalFortran/test_MinimalFortran.py

@@ -15,13 +15,16 @@
 from fab.steps.link import link_exe
 from fab.steps.preprocess import preprocess_fortran
 
+import pytest
+
 PROJECT_SOURCE = Path(__file__).parent / 'project-source'
 
 
 def test_MinimalFortran(tmp_path):
 
     # build
-    with BuildConfig(fab_workspace=tmp_path, project_label='foo', multiprocessing=False) as config:
+    with BuildConfig(fab_workspace=tmp_path, project_label='foo', multiprocessing=False) as config, \
+         pytest.warns(UserWarning, match="removing managed flag"):
         grab_folder(config, PROJECT_SOURCE),
         find_source_files(config),
         preprocess_fortran(config),

tests/system_tests/git/test_git.py

@@ -38,21 +38,25 @@ def url(self):
         return 'https://github.com/metomi/fab-test-data.git'
 
     def test_checkout_url(self, tmp_path, url, config):
-        git_checkout(config, src=url, dst_label='tiny_fortran')
-        # todo: The commit will keep changing. Perhaps make a non-changing branch
-        assert current_commit(config.source_root / 'tiny_fortran') == '3cba55e'
+        with pytest.warns(UserWarning, match="_metric_send_conn not set, cannot send metrics"):
+            git_checkout(config, src=url, dst_label='tiny_fortran')
+            # todo: The commit will keep changing. Perhaps make a non-changing branch
+            assert current_commit(config.source_root / 'tiny_fortran') == '3cba55e'
 
     def test_checkout_branch(self, tmp_path, url, config):
-        git_checkout(config, src=url, dst_label='tiny_fortran', revision='main')
-        assert current_commit(config.source_root / 'tiny_fortran') == '3cba55e'
+        with pytest.warns(UserWarning, match="_metric_send_conn not set, cannot send metrics"):
+            git_checkout(config, src=url, dst_label='tiny_fortran', revision='main')
+            assert current_commit(config.source_root / 'tiny_fortran') == '3cba55e'
 
     def test_checkout_tag(self, tmp_path, url, config):
-        git_checkout(config, src=url, dst_label='tiny_fortran', revision='early')
-        assert current_commit(config.source_root / 'tiny_fortran') == 'ee56489'
+        with pytest.warns(UserWarning, match="_metric_send_conn not set, cannot send metrics"):
+            git_checkout(config, src=url, dst_label='tiny_fortran', revision='early')
+            assert current_commit(config.source_root / 'tiny_fortran') == 'ee56489'
 
     def test_checkout_commit(self, tmp_path, url, config):
-        git_checkout(config, src=url, dst_label='tiny_fortran', revision='ee5648928893701c5dbccdbf0561c0038352a5ff')
-        assert current_commit(config.source_root / 'tiny_fortran') == 'ee56489'
+        with pytest.warns(UserWarning, match="_metric_send_conn not set, cannot send metrics"):
+            git_checkout(config, src=url, dst_label='tiny_fortran', revision='ee5648928893701c5dbccdbf0561c0038352a5ff')
+            assert current_commit(config.source_root / 'tiny_fortran') == 'ee56489'
 
 
 # todo: we could do with a test to ensure left-over files from previous fetches are cleaned away
@@ -65,18 +69,25 @@ def repo_url(self, tmp_path):
         shutil.unpack_archive(Path(__file__).parent / 'repo.tar.gz', tmp_path)
         return f'file://{tmp_path}/repo'
 
+    @pytest.mark.filterwarnings("ignore: Python 3.14 will, "
+                                "by default, filter extracted tar archives "
+                                "and reject files or modify their metadata. "
+                                "Use the filter argument to control this behavior.")
     def test_vanilla(self, repo_url, config):
 
         # checkout master
-        git_checkout(config, src=repo_url, dst_label='tiny_fortran', revision='master')
-        check_file = config.source_root / 'tiny_fortran/file1.txt'
-        assert 'This is sentence one in file one.' in open(check_file).read()
+        with pytest.warns(UserWarning, match="_metric_send_conn not set, cannot send metrics"):
+            git_checkout(config, src=repo_url, dst_label='tiny_fortran', revision='master')
+            check_file = config.source_root / 'tiny_fortran/file1.txt'
+            assert 'This is sentence one in file one.' in open(check_file).read()
 
-        git_merge(config, src=repo_url, dst_label='tiny_fortran', revision='experiment_a')
-        assert 'This is sentence one, with Experiment A modification.' in open(check_file).read()
+        with pytest.warns(UserWarning, match="_metric_send_conn not set, cannot send metrics"):
+            git_merge(config, src=repo_url, dst_label='tiny_fortran', revision='experiment_a')
+            assert 'This is sentence one, with Experiment A modification.' in open(check_file).read()
 
         with pytest.raises(RuntimeError):
             git_merge(config, src=repo_url, dst_label='tiny_fortran', revision='experiment_b')
 
         # The conflicted merge must have been aborted, check that we can do another checkout of master
-        git_checkout(config, src=repo_url, dst_label='tiny_fortran', revision='master')
+        with pytest.warns(UserWarning, match="_metric_send_conn not set, cannot send metrics"):
+            git_checkout(config, src=repo_url, dst_label='tiny_fortran', revision='master')

tests/system_tests/grab_archive/test_grab_archive.py

@@ -8,11 +8,14 @@
 
 from fab.steps.grab.archive import grab_archive
 
+import pytest
+
 
 class TestGrabArchive(object):
 
     def test(self, tmp_path):
-        tar_file = Path(__file__).parent / '../git/tiny_fortran.tar'
-        grab_archive(config=mock.Mock(source_root=tmp_path), src=tar_file)
+        with pytest.warns(UserWarning, match="_metric_send_conn not set, cannot send metrics"):
+            tar_file = Path(__file__).parent / '../git/tiny_fortran.tar'
+            grab_archive(config=mock.Mock(source_root=tmp_path), src=tar_file)
 
-        assert (tmp_path / 'tiny_fortran/src/my_mod.F90').exists()
+            assert (tmp_path / 'tiny_fortran/src/my_mod.F90').exists()

tests/system_tests/psyclone/skeleton/algorithm/algorithm_mod.x90

@@ -46,7 +46,7 @@ contains
     ! Set the new field to a constant value and compute the divergence of it
     divergence => get_div()
     s = 2.0_r_def
-    call invoke( name = "Compute divergence",  &
+    call invoke( name = "Compute_divergence",  &
                  setval_c(field_2, s        ), &
                  setval_c(field_1, 0.0_r_def), &
                  my_kernel_type(field_1, field_2, divergence) )