Merge remote-tracking branch 'origin/main' into sc/improve-numeric-readability-scores-tutorial

Author: samcunliffe

.pre-commit-config.yaml

@@ -1,7 +1,7 @@
 exclude: ^{{cookiecutter.project_slug}}/|^tests/data/test_package_generation/
 repos:
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.11.12
+    rev: v0.12.1
     hooks:
       - id: ruff
         args:
@@ -24,15 +24,15 @@ repos:
     hooks:
       - id: toml-sort-fix
   - repo: https://github.com/pre-commit/mirrors-mypy
-    rev: v1.16.0
+    rev: v1.16.1
     hooks:
       - id: mypy
         args:
           - --config-file=pyproject.toml
         additional_dependencies:
           - pytest
   - repo: https://github.com/rbubley/mirrors-prettier
-    rev: v3.5.3
+    rev: v3.6.2
     hooks:
       - id: prettier
         args:
@@ -49,7 +49,7 @@ repos:
           - --fix=lf
       - id: trailing-whitespace
   - repo: https://github.com/python-jsonschema/check-jsonschema
-    rev: 0.33.0
+    rev: 0.33.1
     hooks:
       # Schemas taken from https://www.schemastore.org/json/
       - id: check-jsonschema

CONTRIBUTING.md

@@ -75,11 +75,9 @@ Pages all live in the `docs/pages` sub-directory, and are written in markdown.
 To build the webpage locally (for testing)
 
 1. [Install jekyll]
-2. Run `bundle install` from the `docs/` directory of this repository to
-   install dependencies.
-3. Run `bundle exec jekyll serve` from the root directory of this repository.
-   This should fire up a local web server and tell you its address. By default
-   the server will automatically refresh the HTML pages if any changes are made
+2. Run `make serve` from the `docs/` directory of this repository to
+   install dependencies and start a local web server.
+   The server will automatically refresh the HTML pages if any changes are made
    to the markdown sources.
 
 See the [jekyll docs] for more info.

docs/Makefile

@@ -0,0 +1,24 @@
+SHELL := /bin/bash
+.PHONY: help serve build install clean check
+
+help: ## Show this help
+	@echo
+	@grep -E '^[a-zA-Z_0-9-]+:.*?## .*$$' $(MAKEFILE_LIST) \
+		| awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%s\033[0m|%s\n", $$1, $$2}' \
+        | column -t -s '|'
+	@echo
+
+serve: install ## Start a local server and serve the site
+	bundle exec jekyll serve
+
+build: install ## Build the site
+	bundle exec jekyll build
+
+install: check ## Pull all jekyll dependencies
+	bundle install
+
+clean: ## Remove build files
+	rm -rf _site
+
+check: ## Check ruby (bundle) is installed
+	@command -v bundle &> /dev/null || { echo >&2 "Please install ruby >= 2.7 to use Jekyll"; exit 1; }

docs/_includes/header_custom.html

@@ -1,17 +1,30 @@
-<button class="btn js-toggle-dark-mode" aria-label="Switch to light mode">
-  ☼
-</button>
+<div class="js-toggle-dark-mode-wrapper">
+  <button
+    class="btn js-toggle-dark-mode"
+    aria-label="Switch to light mode"
+    type="button"
+  >
+    ☼
+  </button>
+</div>
 
 <script>
   const toggleDarkMode = document.querySelector(".js-toggle-dark-mode");
+
+  const setHtmlThemeAttr = (theme) => {
+    document.documentElement.setAttribute("data-theme", theme);
+  };
+
   jtd.addEvent(toggleDarkMode, "click", function () {
     if (jtd.getTheme() === "light") {
       jtd.setTheme("dark");
+      setHtmlThemeAttr("dark");
       toggleDarkMode.textContent = "☼";
       toggleDarkMode.ariaLabel = "Switch to light mode";
       localStorage.setItem("theme", "dark");
     } else {
       jtd.setTheme("light");
+      setHtmlThemeAttr("light");
       toggleDarkMode.textContent = "☾";
       toggleDarkMode.ariaLabel = "Switch to dark mode";
       localStorage.setItem("theme", "light");
@@ -22,12 +35,9 @@
    * Meanwhile, we check each time if there is a theme written to local storage and obey it.
    */
   window.addEventListener("DOMContentLoaded", function () {
-    if (localStorage.getItem("theme") === "dark") {
-      jtd.setTheme("dark");
-      toggleDarkMode.textContent = "☼";
-    } else {
-      jtd.setTheme("light");
-      toggleDarkMode.textContent = "☾";
-    }
+    const theme = localStorage.getItem("theme") === "dark" ? "dark" : "light";
+    jtd.setTheme(theme);
+    setHtmlThemeAttr(theme);
+    toggleDarkMode.textContent = theme === "dark" ? "☼" : "☾";
   });
 </script>

docs/_sass/custom/custom.scss

@@ -1,3 +1,11 @@
+:root {
+  --outline-color: #{$outline-color-light};
+}
+
+[data-theme="dark"] {
+  --outline-color: #{$outline-color-dark};
+}
+
 html,
 body {
   height: 100%;
@@ -28,3 +36,71 @@ div.site-logo {
   width: 100%;
   color: $body-text-color;
 }
+
+// Dark mode link styles
+html[data-theme="dark"] {
+  .main-header a,
+  .main-header button,
+  .side-bar a {
+    color: $link-color-dark;
+  }
+
+  main a,
+  footer a {
+    color: $link-color-dark;
+    text-decoration: underline;
+    text-decoration-color: $link-color-dark;
+    text-decoration-thickness: 1px;
+    transition:
+      text-decoration-thickness 0.2s ease-in-out,
+      text-underline-offset 0.2s ease-in-out;
+  }
+
+  main a:hover,
+  footer a:hover {
+    text-decoration-color: $link-color-dark;
+    text-decoration-thickness: 2px;
+    text-underline-offset: 3px;
+  }
+}
+
+// Label colors
+main {
+  .label-green {
+    background-color: $label-success-bg;
+  }
+
+  .label-red {
+    background-color: $label-error-bg;
+  }
+}
+
+// Outline styles
+.search:focus-within,
+.btn:focus,
+.btn:active,
+.btn:focus:hover,
+a:focus-visible,
+summary:focus-visible {
+  outline: none;
+  box-shadow: 0 0 0 3px var(--outline-color);
+  border-radius: 2px;
+  transition: box-shadow 0.2s ease;
+}
+
+.aux-nav .aux-nav-list-item {
+  padding: 5px;
+}
+
+.nav-list-item {
+  padding-left: 1px;
+  padding-right: 1px;
+}
+
+.js-toggle-dark-mode {
+  height: 100%;
+}
+
+.js-toggle-dark-mode-wrapper {
+  padding: 5px;
+}

docs/_sass/custom/setup.scss

@@ -0,0 +1,13 @@
+// Color palette
+$blue-400: #4da6ff;
+$green-700: #00755c;
+$red-600: #d13c3c;
+$purple-500: rgba(215, 186, 255, 0.65);
+$lavender: #b69cff;
+
+// Semantic mappings
+$link-color-dark: $blue-400;
+$label-success-bg: $green-700;
+$label-error-bg: $red-600;
+$outline-color-light: $lavender;
+$outline-color-dark: $purple-500;

hooks/post_gen_project.py

@@ -22,15 +22,15 @@ def main(initialise_git_repository: str, deploy_docs_to_github_pages: str) -> in
     if initialise_git_repository == "True":
         try:
             # initialise git repo
-            subprocess.run(  # noqa: S603
+            subprocess.run(
                 [  # noqa: S607
                     "git",
                     "init",
                 ],
                 check=True,
             )
             # old versions of git still default to `master`
-            subprocess.run(  # noqa: S603
+            subprocess.run(
                 [  # noqa: S607
                     "git",
                     "branch",
@@ -51,7 +51,7 @@ def main(initialise_git_repository: str, deploy_docs_to_github_pages: str) -> in
 
         try:
             # check for presence of GitHub CLI
-            subprocess.run(  # noqa: S603
+            subprocess.run(
                 [  # noqa: S607
                     "gh",
                     "--version",

tests/data/test_package_generation/.pre-commit-config.yaml

@@ -1,6 +1,6 @@
 repos:
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.11.12
+    rev: v0.12.1
     hooks:
       - id: ruff
       - id: ruff-format
@@ -19,11 +19,11 @@ repos:
     hooks:
       - id: toml-sort-fix
   - repo: https://github.com/pre-commit/mirrors-mypy
-    rev: v1.16.0
+    rev: v1.16.1
     hooks:
       - id: mypy
   - repo: https://github.com/rbubley/mirrors-prettier
-    rev: v3.5.3
+    rev: v3.6.2
     hooks:
       - id: prettier
         args:
@@ -41,7 +41,7 @@ repos:
           - --fix=lf
       - id: trailing-whitespace
   - repo: https://github.com/python-jsonschema/check-jsonschema
-    rev: 0.33.0
+    rev: 0.33.1
     hooks:
       # Schemas taken from https://www.schemastore.org/json/
       - id: check-jsonschema

tests/test_git_init.py

@@ -47,7 +47,7 @@ def test_initialisation_of_git_repo(
 
     try:
         # check for presence of GitHub CLI
-        subprocess.run(  # noqa: S603
+        subprocess.run(
             [  # noqa: S607
                 "gh",
                 "--version",

{{cookiecutter.project_slug}}/.pre-commit-config.yaml

@@ -1,6 +1,6 @@
 repos:
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.11.12
+    rev: v0.12.1
     hooks:
       - id: ruff
       - id: ruff-format
@@ -19,11 +19,11 @@ repos:
     hooks:
       - id: toml-sort-fix
   - repo: https://github.com/pre-commit/mirrors-mypy
-    rev: v1.16.0
+    rev: v1.16.1
     hooks:
       - id: mypy
   - repo: https://github.com/rbubley/mirrors-prettier
-    rev: v3.5.3
+    rev: v3.6.2
     hooks:
       - id: prettier
         args:
@@ -41,7 +41,7 @@ repos:
           - --fix=lf
       - id: trailing-whitespace
   - repo: https://github.com/python-jsonschema/check-jsonschema
-    rev: 0.33.0
+    rev: 0.33.1
     hooks:
       # Schemas taken from https://www.schemastore.org/json/
       - id: check-jsonschema