woof woof

.cruft.json

@@ -1,6 +1,6 @@
 {
   "template": "https://github.com/arup-group/cookiecutter-pypackage.git",
-  "commit": "b4e39b80b4d9b4d6682ab18635a98a097b292a46",
+  "commit": "bb2bab415eded9682b2c1d465a281450ec922f1c",
   "checkout": null,
   "context": {
     "cookiecutter": {
@@ -15,11 +15,13 @@
       "project_short_description": "The Population activity Modeller (PAM) is a python API for activity sequence modelling.",
       "upload_pypi_package": "y",
       "upload_conda_package": "y",
+      "upload_aws_image": "n",
       "conda_channel": "city-modelling-lab",
       "command_line_interface": "y",
       "create_docker_file": "y",
       "create_author_file": "n",
       "create_jupyter_notebook_directory": "y",
+      "check_docs_accessibility_in_CI": "n",
       "open_source_license": "MIT license",
       "_template": "https://github.com/arup-group/cookiecutter-pypackage.git"
     }

.github/workflows/pr-ci.yml

@@ -15,7 +15,16 @@ on:
       - "!.github/workflows/pr-ci.yml"
 
 jobs:
+  lint:
+    if: github.event.repository.private
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+    - uses: pre-commit/action@v3.0.1
+
   test:
+    needs: lint
+    if: always() && (needs.lint.result  == 'success' || needs.lint.result  == 'skipped')
     strategy:
       matrix:
         os: [windows-latest, ubuntu-latest, macos-latest]
@@ -31,14 +40,16 @@ jobs:
       upload_to_codecov: false
 
   test-coverage:
+    needs: lint
+    if: always() && (needs.lint.result  == 'success' || needs.lint.result  == 'skipped')
     uses: arup-group/actions-city-modelling-lab/.github/workflows/python-install-lint-test.yml@main
     with:
       os: ubuntu-latest
       py3version: "12"
       notebook_kernel: pam
       lint: false
       pytest_args: 'tests/'  # ignore example notebooks
-      upload_to_codecov: true
+      upload_to_codecov: ${{ github.event.repository.visibility == 'public' }}  # only attempt to upload if the project is public
 
   memory-profile:
     uses: arup-group/actions-city-modelling-lab/.github/workflows/python-memory-profile.yml@main

.pa11yci

@@ -0,0 +1,24 @@
+{
+  "defaults": {
+    "reporters": [
+        "cli",
+      [
+        "pa11y-ci-reporter-html",
+        { "destination": "./reports/pa11y", "includeZeroIssues": false }
+      ]
+    ],
+    "timeout": 100000,
+    "wait": 2000,
+    "ignore": ["color-contrast"],
+    "runners": [
+      "htmlcs", "axe"
+    ],
+    "hideElements": "[id^='__codelineno'], .md-search__form, #__toc, clipboard-copy"
+  },
+  "standard": "WCAG2AA",
+  "comments": [
+    "Ignoring color-contrast due to https://github.com/pa11y/pa11y/issues/697.",
+    "Hiding `clipboard-copy` until https://github.com/danielfrg/mkdocs-jupyter/pull/206 is merged.",
+    "Hiding `[id^='__codelineno'], .md-search__form, #__toc` due to known false positives in mkdocs-material: https://github.com/squidfunk/mkdocs-material/discussions/4102"
+  ]
+}

CONTRIBUTING.md

@@ -36,19 +36,19 @@ Look at the [development guide in our documentation](https://arup-group.github.i
 To contribute changes:
 
 1. Fork the project on GitHub.
-2. Create a feature branch to work on in your fork (`git checkout -b new-fix-or-feature`).
-3. Test your changes using `pytest`.
-4. Commit your changes to the feature branch (you should have `pre-commit` installed to ensure your code is correctly formatted when you commit changes).
-5. Push the branch to GitHub (`git push origin new-fix-or-feature`).
-6. On GitHub, create a new [pull request](https://github.com/arup-group/pam/pull/new/main) from the feature branch.
+1. Create a feature branch to work on in your fork (`git checkout -b new-fix-or-feature`).
+1. Test your changes using `pytest`.
+1. Commit your changes to the feature branch (you should have `pre-commit` installed to ensure your code is correctly formatted when you commit changes).
+1. Push the branch to GitHub (`git push origin new-fix-or-feature`).
+1. On GitHub, create a new [pull request](https://github.com/arup-group/pam/pull/new/main) from the feature branch.
 
 ### Pull requests
 
 Before submitting a pull request, check whether you have:
 
-* Added your changes to `CHANGELOG.md`.
-* Added or updated documentation for your changes.
-* Added tests if you implemented new functionality.
+- Added your changes to `CHANGELOG.md`.
+- Added or updated documentation for your changes.
+- Added tests if you implemented new functionality.
 
 When opening a pull request, please provide a clear summary of your changes!
 

docs/static/extras.css

@@ -7,4 +7,25 @@ div.doc-contents:not(.first) {
 /* Allow tables to be horizontally scrollable. */
 .md-typeset__scrollwrap {
   overflow-x: auto;
-}
+}
+/* Improve contrast of text in rendered Jupyter notebook codeblocks. */
+.jp-Notebook {
+  --jp-cell-prompt-not-active-opacity: 1;
+}
+.jp-InputArea-editor {
+  --jp-cell-editor-background: var(--md-code-bg-color);
+}
+.highlight-ipynb {
+  --jp-mirror-editor-number-color: var(--md-code-hl-number-color);
+  --jp-mirror-editor-string-color: var(--md-code-hl-string-color);
+  --jp-mirror-editor-operator-color: var(--md-code-hl-operator-color);
+  --jp-mirror-editor-meta-color: var(--md-code-hl-operator-color);
+  --jp-mirror-editor-comment-color: var(--md-code-hl-comment-color);
+  --jp-mirror-editor-keyword-color: var(--md-code-hl-keyword-color);
+  --jp-mirror-editor-builtin-color: var(--md-code-hl-keyword-color);
+  --jp-mirror-editor-variable-2-color: var(--md-code-hl-punctuation-color);
+  --jp-mirror-editor-punctuation-color: var(--md-code-hl-punctuation-color);
+  --jp-mirror-editor-property-color: var(--md-code-hl-punctuation-color);
+  --jp-mirror-editor-variable-color: var(--md-code-hl-variable-color);
+  --jp-mirror-editor-def-color: var(--md-code-hl-constant-color);
+}

docs/static/hooks.py

@@ -1,3 +1,5 @@
+"""Hooks to run when building documentation."""
+
 import tempfile
 from pathlib import Path
 
@@ -10,8 +12,17 @@
 
 # Bump priority to ensure files are moved before jupyter notebook conversion takes place
 @mkdocs.plugins.event_priority(50)
-def on_files(files: list, config: dict, **kwargs):
-    """Link (1) top-level files to mkdocs files and (2) generate the python API documentation."""
+def on_files(files: list, config: dict, **kwargs) -> list:
+    """Link (1) top-level files to mkdocs files and (2) generate the python API documentation.
+
+    Args:
+        files (list): mkdocs file list.
+        config (dict): mkdocs config dictionary.
+        **kwargs: Automatic MKDocs hook inputs.
+
+    Returns:
+        list: Updated mkdocs file list.
+    """
     for file in sorted(Path("./examples").glob("*.ipynb")):
         files.append(_new_file(file, config))
         _get_nav_list(config["nav"], "Examples").append(file.as_posix())
@@ -48,7 +59,7 @@ def _new_file(path: Path, config: dict, src_dir: str = ".") -> File:
 
 
 def _api_gen(files: list, config: dict) -> dict:
-    """Project Python API generator
+    """Project Python API generator.
 
     Args:
         files (list): mkdocs file list.
@@ -78,6 +89,7 @@ def _py_to_md(filepath: Path, api_nav: dict, config: dict) -> File:
         filepath (Path): Path to python file relative to the package source code directory.
         api_nav (dict): Nested dictionary to fill with mkdocs navigation entries.
         config (Config): mkdocs config dictionary.
+
     Returns:
         File: mkdocs object that links the temp file to the docs directory, ready to be added to the mkdocs file list.
     """
@@ -112,7 +124,6 @@ def _update_nav(api_nav: dict, config: dict) -> None:
         api_nav (dict): Python API navigation tree.
         config (dict): mkdocs config dictionary (in which `nav` can be found).
     """
-
     api_reference_nav = {
         "Python API": [*api_nav.pop("top_level"), *[{k: v} for k, v in api_nav.items()]]
     }
@@ -121,6 +132,7 @@ def _update_nav(api_nav: dict, config: dict) -> None:
 
 def _get_nav_list(nav: list[dict | str], ref: str) -> list:
     """Get navigation entry sub-page list.
+
     Navigation list entries can be dictionaries or strings.
     Sub-list entries can then also be dictionaries or strings. E.g.,
 
@@ -144,6 +156,6 @@ def on_post_build(**kwargs):
     """After mkdocs has finished building the docs, remove the temporary directory of markdown files.
 
     Args:
-        config (Config): mkdocs config dictionary (unused).
+        **kwargs: Automatic MKDocs hook inputs.
     """
     TEMPDIR.cleanup()

mkdocs.yml

@@ -36,13 +36,12 @@ markdown_extensions:
       anchor_linenums: true
       line_spans: __span
       pygments_lang_class: true
-  - pymdownx.inlinehilite
+  - pymdownx.inlinehilite:
+      style_plain_text: shell
   - pymdownx.superfences
   - pymdownx.snippets
   - pymdownx.tabbed:
       alternate_style: true
-  - pymdownx.tasklist:
-      clickable_checkbox: true
   - toc:
       permalink: "#"
       toc_depth: 3

pyproject.toml

@@ -2,7 +2,7 @@
 minversion = "6.0"
 # opts:
 # `--strict-markers` - Raise error on unexpected pytest markers being used (add new markers to `markers` config)
-# `-n2` - parallelise over two threads (uses pytest-xdist)
+# `-nauto` - parallelise over as many threads are available (uses pytest-xdist). This auto-selects 1 thread when using the `--pdb` debugging flag.
 # `--nbmake --nbmake-kernel=pam` - test example notebooks using the "pam" notebook kernel (uses nbmake)
 # `--cov --cov-report=xml --cov-config=pyproject.toml` - generate coverage report for tests (uses pytest-cov; call `--no-cov` in CLI to switch off; `--cov-config` include to avoid bug)
 # `-m 'not high_mem'` - Do not run tests marked as consuming large amounts of memory (call `-m "high_mem"` in CLI to invert this; only `high_mem` marked tests will be run)