Merge remote-tracking branch 'upstream/master'

MetOffice · Oct 16, 2024 · d42e909 · d42e909
2 parents cd4b2fe + b121ef8
commit d42e909
Show file tree

Hide file tree

Showing 18 changed files with 541 additions and 74 deletions.
diff --git a/.github/bin/update-index b/.github/bin/update-index
@@ -0,0 +1,46 @@
+#!/usr/bin/env python3
+##############################################################################
+# Add a new release's documentation to the documentation index page.
+#
+# Usage:
+#   update-index <index file> <release name>
+##############################################################################
+from argparse import ArgumentParser
+from pathlib import Path
+from xml.etree import ElementTree
+
+if __name__ == '__main__':
+    cli_parser = ArgumentParser(description="Add a new release to the index")
+    cli_parser.add_argument('index_file', type=Path,
+                            help="Filename of index file.")
+    cli_parser.add_argument('release',
+                            help="Release tag name")
+    arguments = cli_parser.parse_args()
+
+    ns = {'html': 'http://www.w3.org/1999/xhtml'}
+
+    ElementTree.register_namespace('', 'http://www.w3.org/1999/xhtml')
+    index_doc = ElementTree.parse(arguments.index_file)
+
+    release_list = index_doc.find('.//html:ul[@id="releases"]', namespaces=ns)
+    if release_list is None:
+        raise Exception("Unable to find release list")
+
+    last_child = list(release_list)[-1]
+    item_indent = release_list.text
+    list_indent = last_child.tail
+    last_child.tail = item_indent
+
+    new_release = ElementTree.SubElement(release_list, 'li')
+    new_release.tail = list_indent
+    new_anchor = ElementTree.SubElement(new_release, 'a')
+    new_anchor.attrib['href'] = arguments.release
+    new_anchor.text = arguments.release
+
+    document_text = ElementTree.tostring(index_doc.getroot(), encoding='unicode')
+    with arguments.index_file.open('w') as fhandle:
+        # Doctype is not preserved by the parser so we need to recreate it.
+        #
+        print('''<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
+   "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">''', file=fhandle)
+        print(document_text, file=fhandle)
diff --git a/.github/workflows/performance.yml b/.github/workflows/performance.yml
@@ -4,7 +4,9 @@ on:
   push:
     branches:
       - master
-
+  workflow_run:
+    workflows: ["sphinx"]
+    types: [completed]
 
 
 jobs:

diff --git a/.github/workflows/sphinx.yml b/.github/workflows/sphinx.yml
@@ -38,7 +38,7 @@ jobs:
       - name: Install Python
         uses: actions/setup-python@v2
         with:
-          python-version: 3.8
+          python-version: 3.11
 
       - name: Cache pip
         uses: actions/cache@v2
@@ -97,6 +97,8 @@ jobs:
           set -x
           rsync -a stylist/documentation/build/html/ gh-pages/${{github.ref_name}}
           git -C gh-pages add ${{github.ref_name}}
+          stylist/.github/bin/update-index gh-pages/index.html ${{github.ref_name}}
+          git -C gh-pages add index.html
 
       - name: Commit documentation
         if: github.event_name == 'push'

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -28,6 +28,7 @@ below:
 * Matt Shin (Met Office, UK)
 * Bilal Chughtai (Met Office, UK)
 * James Cuninngham-Smith (Met Office, UK)
+* Sam Clarke-Green (Met Office, UK)
 
 (All contributors are identifiable with email addresses in the version control
 logs or otherwise.)

diff --git a/documentation/source/_templates/crown-copyright.html b/documentation/source/_templates/crown-copyright.html
@@ -0,0 +1,11 @@
+{# Crown copyright is presented differently to normal copyright. #}
+{# This template uses details from conf.py #}
+{% if show_copyright and copyright %}
+<p class="copyright">
+{% if hasdoc('copyright') %}
+{%     trans path=pathto('copyright'), copyright=copyright|e %}&copy; <a href="{{path}}">Copyright</a> {{copyright}}.{% endtrans %}
+{% else %}
+{%     trans copyright=copyright|e %}&copy; Crown Copyright {{copyright}}.{% endtrans %}
+{% endif %}
+</p>
+{% endif %}
diff --git a/documentation/source/conf.py b/documentation/source/conf.py
@@ -23,7 +23,7 @@
 # -- Project information -----------------------------------------------------
 
 project = 'Stylist'
-copyright = '2022, Crown Copyright'
+copyright = '2024, Met Office. All rights reserved'
 author = 'Stylist Developers'
 
 # Headline version for archiving purposes.
@@ -82,7 +82,20 @@
 # The theme to use for HTML and HTML Help pages. See the documentation for
 # a list of builtin themes.
 #
-html_theme = 'sphinx_rtd_theme'
+html_theme = 'pydata_sphinx_theme'
+
+html_theme_options = {
+    "icon_links": [
+        {
+            "name": "GitHub",
+            "url": "https://github.com/MetOffice/stylist",
+            "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,

diff --git a/pyproject.toml b/pyproject.toml
@@ -7,18 +7,25 @@ name='stylist'
 description="Flexible source code style checking tool"
 requires-python = '>=3.7, <4'
 license = {text = 'BSD 3-Clause License'}
-classifiers = ['Programming Language :: Python :: 3']
 dependencies = ['fparser >= 0.1.2']
-dynamic = ['version']
+dynamic = ['version', 'readme']
+keywords = ['linter', 'fortran']
+classifiers = [
+    'Development Status :: 3 - Alpha',
+    'Intended Audience :: Developers',
+    'Topic :: Software Development :: Quality Assurance',
+    'License :: OSI Approved :: BSD License',
+    'Programming Language :: Python :: 3'
+]
 
 
 [project.optional-dependencies]
 dev = ['check-manifest', 'flake8']
 test = ['pytest', 'pytest-cov', 'mypy']
 performance = ['pytest', 'pytest-benchmark', 'matplotlib']
-docs = ['sphinx',
+docs = ['sphinx < 7.0.0',
         'sphinx-autodoc-typehints',
-        'sphinx-rtd-theme>=1.2.2']
+        'pydata-sphinx-theme>=0.15.2']
 release = ['setuptools', 'wheel', 'twine']
 
 [project.scripts]
@@ -31,7 +38,7 @@ documentation = 'https://metoffice.github.io/stylist'
 repository = 'https://github.com/MetOffice/stylist/'
 
 [tool.setuptools.dynamic]
-readme = {file = 'README.md'}
+readme = {file = 'README.rst'}
 version = {attr = 'stylist.__version__'}
 
 [tool.setuptools.packages.find]

diff --git a/setup.cfg b/setup.cfg
diff --git a/source/stylist/__main__.py b/source/stylist/__main__.py
@@ -13,7 +13,7 @@
 from pathlib import Path
 import sys
 from textwrap import indent
-from typing import List, Sequence
+from typing import List, Sequence, Union
 
 from stylist import StylistException
 from stylist.configuration import (Configuration,
@@ -25,6 +25,11 @@
 from stylist.style import Style
 
 
+# Paths to site-wide and per-user style files
+site_file = Path("/etc/stylist.py")
+user_file = Path.home() / ".stylist.py"
+
+
 def __parse_cli() -> argparse.Namespace:
     """
     Parse the command line for stylist arguments.
@@ -107,10 +112,30 @@ def __process(candidates: List[Path], styles: Sequence[Style]) -> List[Issue]:
     return issues
 
 
-def __configure(project_file: Path) -> Configuration:
-    configuration = load_configuration(project_file)
-    # TODO /etc/fab.ini
-    # TODO ~/.fab.ini - Path.home() / '.fab.ini'
+def __configure(project_file: Path) -> Union[Configuration, None]:
+    """
+    Load configuration styles in order of specificity
+
+    Load the global site configuration, the per-user configuration, and
+    finally the configuration option provided on the command line.
+    More specific options are allowed to override more general ones,
+    allowing a configuration to built up gradually.
+    """
+
+    candidates = [site_file, user_file, project_file]
+
+    configuration = None
+
+    for target in candidates:
+        if target is None or not target.exists():
+            continue
+
+        style = load_configuration(target)
+        if configuration is None:
+            configuration = style
+        else:
+            configuration.overload(style)
+
     return configuration
 
 
@@ -187,6 +212,11 @@ def main() -> None:
         logger.setLevel(logging.WARNING)
 
     configuration = __configure(arguments.configuration)
+    if configuration is None:
+        # No valid configuration files have been found
+        # FIXME: proper exit handling
+        raise Exception("no valid style files found")
+
     issues = perform(configuration,
                      arguments.source,
                      arguments.style,

diff --git a/source/stylist/configuration.py b/source/stylist/configuration.py
@@ -9,6 +9,8 @@
 
 Configuration may be defined by software or read from a Windows .ini file.
 """
+from __future__ import annotations
+
 from importlib.util import module_from_spec, spec_from_file_location
 from pathlib import Path
 from typing import Dict, List, Tuple, Type
@@ -37,6 +39,10 @@ def add_pipe(self, extension: str, pipe: FilePipe):
     def add_style(self, name: str, style: Style):
         self._styles[name] = style
 
+    def overload(self, other: Configuration) -> None:
+        self._pipes = {**self._pipes, **other._pipes}
+        self._styles = {**self._styles, **other._styles}
+
     @property
     def file_pipes(self) -> Dict[str, FilePipe]:
         return self._pipes