crufts strikes again

.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/commit-ci.yml.rej

@@ -0,0 +1,28 @@
+diff a/.github/workflows/commit-ci.yml b/.github/workflows/commit-ci.yml	(rejected hunks)
+@@ -20,25 +20,3 @@ jobs:
+       py3version: "12"
+       notebook_kernel: pam
+       lint: false
+-
+-  aws-pre-check:
+-    runs-on: ubuntu-latest
+-    outputs:
+-      aws-secrets-exist: ${{ steps.secret-checker.outputs.SECRETS_EXIST }}
+-    steps:
+-      - id: secret-checker
+-        name: 'Check secret access for fast fail'
+-        run: |
+-          echo "SECRETS_EXIST=$AWS_SECRETS_EXIST" >> $GITHUB_OUTPUT
+-          echo "SECRETS_EXIST=$AWS_SECRETS_EXIST" >> $GITHUB_STEP_SUMMARY
+-        env:
+-          AWS_SECRETS_EXIST: ${{ secrets.AWS_ACCESS_KEY_ID != '' && secrets.AWS_SECRET_ACCESS_KEY != '' && secrets.AWS_S3_CODE_BUCKET != '' }}
+-
+-  aws-upload:
+-    needs: [test, aws-pre-check]
+-    if: always() && needs.test.result == 'success' && needs.aws-pre-check.outputs.aws-secrets-exist == 'true'
+-    uses: arup-group/actions-city-modelling-lab/.github/workflows/aws-upload.yml@main
+-    secrets:
+-      AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
+-      AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
+-      AWS_S3_CODE_BUCKET: ${{ secrets.AWS_S3_CODE_BUCKET }}
+\ No newline at end of file

.github/workflows/docs.yml.rej

@@ -0,0 +1,8 @@
+diff a/.github/workflows/docs.yml b/.github/workflows/docs.yml	(rejected hunks)
+@@ -29,4 +29,4 @@ jobs:
+     uses: arup-group/actions-city-modelling-lab/.github/workflows/docs-deploy.yml@main
+     with:
+       deploy_type: update_latest
+-      notebook_kernel: pam
+\ No newline at end of file
++      notebook_kernel: pam

.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"
+  ]
+}

.pre-commit-config.yaml.rej

@@ -0,0 +1,25 @@
+diff a/.pre-commit-config.yaml b/.pre-commit-config.yaml	(rejected hunks)
+@@ -8,22 +8,11 @@ repos:
+       - id: check-added-large-files
+         args: ["--maxkb=1000"]
+
+-  - repo: https://github.com/psf/black
+-    rev: 24.2.0
+-    hooks:
+-      - id: black
+-
+   - repo: https://github.com/astral-sh/ruff-pre-commit  # https://beta.ruff.rs/docs/usage/#github-action
+-    rev: v0.3.0
++    rev: v0.6.8
+     hooks:
+       - id: ruff
+         args: [ --fix, --exit-non-zero-on-fix ]
+-  - repo: https://github.com/nbQA-dev/nbQA
+-    rev: 1.8.3
+-    hooks:
+-      - id: nbqa-black
+-      - id: nbqa-ruff
+-        args: [ --fix, --exit-non-zero-on-fix ]
+
+   - repo: local
+     hooks:

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!
 

CONTRIBUTING.md.rej

@@ -0,0 +1,52 @@
+diff a/CONTRIBUTING.md b/CONTRIBUTING.md	(rejected hunks)
+@@ -4,11 +4,12 @@ We're really glad you're reading this, because we need volunteer developers to h
+
+ Some of the resources to look at if you're interested in contributing:
+
+-* Look at open issues tagged with ["help wanted"](https://github.com/arup-group/pam/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22) and ["good first issue"](https://github.com/arup-group/pam/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)
+-* Look at the [contributing guide in our documentation](https://arup-group.github.io/pam/contributing)
++- Look at open issues tagged with ["help wanted"](https://github.com/arup-group/pam/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22) and ["good first issue"](https://github.com/arup-group/pam/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)
++- Look at the [contributing guide in our documentation](https://arup-group.github.io/pam/contributing)
+
+ ## Licensing
+ By contributing to pam, i.e. through opening a pull request, you represent that your contributions are your own original work and that you have the right to license them, and you agree that your contributions are licensed under the MIT license.
++
+ ## Reporting bugs and requesting features
+
+ You can open an issue on GitHub to report bugs or request new pam features.
+@@ -79,24 +80,23 @@ When adding docstrings, we request you use the [Google docstring style](https://
+
+ ### Pre-release
+
+-- [ ] Make sure all unit and integration tests pass (This is best done by creating a pre-release pull request).
+-- [ ] Re-run tutorial Jupyter notebooks (`pytest examples/ --overwrite`).
+-- [ ] Make sure documentation builds without errors (`mike deploy [version]`, where `[version]` is the current minor release of the form `X.Y`).
+-- [ ] Make sure the [changelog][changelog] is up-to-date, especially that new features and backward incompatible changes are clearly marked.
++- Make sure all unit and integration tests pass (This is best done by creating a pre-release pull request).
++- Re-run tutorial Jupyter notebooks (`pytest examples/ --overwrite`).
++- Make sure documentation builds without errors (`mike deploy [version]`, where `[version]` is the current minor release of the form `X.Y`).
++- Make sure the [changelog][changelog] is up-to-date, especially that new features and backward incompatible changes are clearly marked.
+
+ ### Create release
+
+-- [ ] Bump the version number in `src/pam/__init__.py`
+-- [ ] Update the [changelog][changelog] with final version number of the form `vX.Y.Z`, release date, and [github `compare` link](https://docs.github.com/en/pull-requests/committing-changes-to-your-project/viewing-and-comparing-commits/comparing-commits) (at the bottom of the page).
+-- [ ] Commit with message `Release vX.Y.Z`, then add a `vX.Y.Z` tag.
+-- [ ] Create a release pull request to verify that the conda package builds successfully.
+-- [ ] Once the PR is approved and merged, create a release through the GitHub web interface, using the same tag, titling it `Release vX.Y.Z` and include all the changelog elements that are *not* flagged as **internal**.
++- Bump the version number in `src/pam/__init__.py`
++- Update the [changelog][changelog] with final version number of the form `vX.Y.Z`, release date, and [github `compare` link](https://docs.github.com/en/pull-requests/committing-changes-to-your-project/viewing-and-comparing-commits/comparing-commits) (at the bottom of the page).
++- Commit with message `Release vX.Y.Z`, then add a `vX.Y.Z` tag.
++- Create a release pull request to verify that the conda package builds successfully.
++- Once the PR is approved and merged, create a release through the GitHub web interface, using the same tag, titling it `Release vX.Y.Z` and include all the changelog elements that are *not- flagged as **internal**.
+
+ ### Post-release
+
+-- [ ] Update the changelog, adding a new `[Unreleased]` heading.
+-- [ ] Update `src/pam/__init__.py` to the next version appended with `.dev0`, in preparation for the next main commit.
+-
++- Update the changelog, adding a new `[Unreleased]` heading.
++- Update `src/pam/__init__.py` to the next version appended with `.dev0`, in preparation for the next main commit.
+
+ <!--- --8<-- [end:docs] -->
+

README.md.rej

@@ -0,0 +1,28 @@
+diff a/README.md b/README.md	(rejected hunks)
+@@ -21,7 +21,6 @@ To install pam
+ ### As a user
+ <!--- --8<-- [start:docs-install-user] -->
+
+-
+ ``` shell
+
+ mamba create -n pam -c conda-forge -c city-modelling-lab cml-pam
+@@ -60,14 +59,13 @@ For more information, see our [documentation](https://arup-group.github.io/pam/l
+ ## Building the documentation
+
+ If you are unable to access the online documentation, you can build the documentation locally.
+-First, [install a development environment of pam](https://arup-group.github.io/pam/latest/contributing/coding/), then deploy the documentation using [mike](https://github.com/jimporter/mike):
++First, [install a development environment of pam](https://arup-group.github.io/pam/latest/contributing/coding/), then deploy the documentation using [MkDocs](https://www.mkdocs.org/):
+
+-```
+-mike deploy develop
+-mike serve
++``` shell
++mkdocs serve
+ ```
+
+-Then you can view the documentation in a browser at http://localhost:8000/.
++Then you can view the documentation in a browser at <http://localhost:8000/>.
+
+ ## Credits
+

docs/overrides/main.html.rej

@@ -0,0 +1,15 @@
+diff a/docs/overrides/main.html b/docs/overrides/main.html	(rejected hunks)
+@@ -3,8 +3,6 @@
+ {% extends "base.html" %}
+
+ <!--Add download button to all pages built from jupyter notebooks-->
+-
+-
+ {% block content %}
+ {% if page.nb_url %}
+ <a href="{{ page.nb_url }}" title="Download Notebook" class="md-content__button md-icon">
+@@ -14,4 +12,3 @@
+
+ {{ super() }}
+ {% endblock content %}
+-

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

mkdocs.yml.rej

@@ -0,0 +1,9 @@
+diff a/mkdocs.yml b/mkdocs.yml	(rejected hunks)
+@@ -14,7 +14,6 @@ theme:
+     - navigation.indexes
+     - navigation.top
+     - content.code.copy
+-    - content.code.annotate
+ repo_url: https://github.com/arup-group/pam/
+ site_dir: .docs
+ markdown_extensions: