Merge branch 'master' into OldTests

MetOffice · Jun 26, 2024 · a32c9ec · a32c9ec
2 parents 5677b42 + 529522b
commit a32c9ec
Show file tree

Hide file tree

Showing 103 changed files with 4,680 additions and 1,816 deletions.
diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
@@ -5,46 +5,53 @@ on: [push, pull_request]
 jobs:
   build:
 
-    runs-on: ubuntu-20.04
+    runs-on: ubuntu-22.04
     strategy:
       max-parallel: 4
       matrix:
         python-version: ['3.7', '3.8', '3.9', '3.10']
 
     steps:
-    - uses: actions/checkout@v1
-    - name: Set up Python ${{ matrix.python-version }}
-      uses: actions/setup-python@v1
-      with:
-        python-version: ${{ matrix.python-version }}
-    - name: Setup Compiler
-      run: |
-        sudo apt-get -y install gcc gfortran
-    - name: Setup LibClang
-      run: |
-        sudo apt-get -y install libclang-dev python-clang
-        SP=~/.local/lib/python${{ matrix.python-version }}/site-packages
-        mkdir -p $SP
-        cp -vr /usr/lib/python3/dist-packages/clang $SP/
-    - name: Install dependencies
-      run: |
-        python -m pip install --upgrade pip
-        pip install -e .
-    - name: Type check with mypy
-      run: |
-        pip install -e .[dev]
-        pip install pytest
-        python -m mypy source tests
-    - name: Code style check with flake8
-      run: |
-        pip install -e .[dev]
-        flake8 . --count --show-source --statistics
-    - name: Unit tests with Pytest
-      run: |
-        pip install .[tests]
-        python -m pytest --cov=fab tests/unit_tests
-
-    - name: System tests with Pytest
-      run: |
-        pip install .[tests]
-        python -m pytest --cov=fab tests/system_tests
+      # Should this step use a cache?
+      #
+      - name: Setup Compiler
+        run: |
+          sudo apt-get -y install llvm clang libclang-dev gcc gfortran
+
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+
+      # The clang binding version has to match the version in the Ubuntu being used.
+      - name: Install Python libraries
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e .
+          pip install clang==14.0
+
+      - name: Type check with mypy
+        run: |
+          pip install -e .[dev]
+          pip install pytest
+          python -m mypy source tests
+
+      - name: Code style check with flake8
+        run: |
+          pip install -e .[dev]
+          flake8 . --count --show-source --statistics
+
+      - name: Unit tests with Pytest
+        run: |
+          pip install .[tests]
+          python -m pytest --cov=fab tests/unit_tests
+
+      - name: System tests with Pytest
+        run: |
+          pip install .[tests]
+          python -m pytest --cov=fab tests/system_tests
diff --git a/.github/workflows/build_docs.yml b/.github/workflows/build_docs.yml
@@ -5,35 +5,48 @@ on: workflow_dispatch
 jobs:
   build-docs:
 
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-22.04
 
     steps:
-    - name: set git user
-      run: |
-        git config --global user.email "metomi@metoffice.gov.uk"
-        git config --global user.name "SciFab Developers"
-    - uses: actions/checkout@v3
-    - uses: actions/setup-python@v4
-      with:
-        python-version: '3.x'
-    - name: install fab
-      run: pip install .[docs]
-    - name: build docs
-      run: |
-        cd docs
-        rm -rf build
-        sphinx-apidoc --separate --module-first -d 5 -f -o source/apidoc ../source/fab
-        make html
-    - name: move built docs to docs root
-      run: |
-        mv docs/build/html/* docs/
-    - name: git add built docs
-      run: |
-        git add docs/*
-    - name: commit
-      run: |
-        git commit -m "docs build"
-    - name: push to gh_pages branch
-      run: |
-        echo "pushing from $GITHUB_REF_NAME to gh_pages"
-        git push --force origin $GITHUB_REF_NAME:gh_pages
+      - name: set git user
+        run: |
+          git config --global user.email "CoreCapabilityDevelopmentTeam@metoffice.gov.uk"
+          git config --global user.name "SciFab Developers"
+
+      - name: Checkout Fab project files
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.x'
+          cache: pip
+
+      - name: Install Python libraries
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e .[docs]
+
+      - name: build docs
+        run: |
+          cd docs
+          rm -rf build
+          sphinx-apidoc --separate --module-first -d 5 -f -o source/apidoc ../source/fab
+          make html
+
+      - name: move built docs to docs root
+        run: |
+          mv docs/build/html/* docs/
+
+      - name: git add built docs
+        run: |
+          git add docs/*
+
+      - name: commit
+        run: |
+          git commit -m "docs build"
+
+      - name: push to gh_pages branch
+        run: |
+          echo "pushing from $GITHUB_REF_NAME to gh_pages"
+          git push --force origin $GITHUB_REF_NAME:gh_pages
diff --git a/.gitignore b/.gitignore
@@ -3,6 +3,11 @@ __pycache__/
 *.py[cod]
 *$py.class
 
+# Build directory for documentation
+docs/build
+docs/source/api
+docs/source/apidoc
+
 # C extensions
 *.so
 

diff --git a/README.md b/README.md
@@ -2,25 +2,29 @@
 
 ![](https://github.com/Metomi/fab/workflows/Build/badge.svg)
 
-The "Fab" build system aims to provide a quick and easy build process tailored towards a
-specific subset of scientific software developers. Quick should be in both use and
-operation. Easy should mean the simple things are simple and the complicated things
-possible.
+The "Fab" project aims to provide the means to quickly and easily compile
+software in a way tailored for scientific software development. It aims to be
+quick both in terms of use and operation. Meanwhile ease should mean the
+simple things are simple and the complicated things are possible.
 
-The tool is not intended for general use outside its intended domain although you are,
-of course, welcome to use it there. Just don't expect high priority to be given to
-features which do not target scientific software development.
+Fab is not intended to replace existing tools for compiling general
+application software. It targets different problems to, for instance, CMake
+derived build systems. This means that if your usage falls outside the focus
+of development you shouldn't expect high priority on your feature requests.
 
 ## Licence
 
 The software is made available under a 3-clause BSD licence.
 
 ## Installation
 
-You may simply use `pip install sci-fab`.
+The tool is easily installed using `pip install sci-fab`.
 
 ## Usage
 
-Although Fab is in its initial development phases right now and much of the
-functionality is yet to be added, the command line interface to the tool is 
-in place and can be run using the command `fab` 
+Fab offers two modes of operation. In "zero configuration" mode it is used
+directly as a tool by running `fab`. This examines the currently selected
+directory and tries to build whatever it finds there.
+
+In "framework" mode it offers a library of building-blocks which a developer
+can use to create a build system customised to the needs of their software.
diff --git a/docs/source/_templates/crown-copyright.html b/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 %}
diff --git a/docs/source/advanced_config.rst b/docs/source/advanced_config.rst
@@ -315,7 +315,7 @@ which most Fab steps accept. (See :ref:`Overriding default collections`)
 
     @step
     def custom_step(state):
-            state._artefact_store['custom_artefacts'] = do_something(state._artefact_store['step 1 artefacts'])
+        state.artefact_store['custom_artefacts'] = do_something(state.artefact_store['step 1 artefacts'])
 
 
     with BuildConfig(project_label='<project label>') as state:
@@ -332,7 +332,7 @@ Steps have access to multiprocessing methods through the
 
     @step
     def custom_step(state):
-        input_files = artefact_store['custom_artefacts']
+        input_files = state.artefact_store['custom_artefacts']
         results = run_mp(state, items=input_files, func=do_something)
 
 

diff --git a/docs/source/api.rst b/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
diff --git a/docs/source/conf.py b/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"]
-# }
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -80,8 +80,9 @@ See also
    config_intro
    writing_config
    advanced_config
+   site-specific-config
    features
-   Api Reference <apidoc/modules>
+   Api Reference <api>
    development
    glossary
    genindex