Merge branch 'main' into project-list-menu

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,23 +1,28 @@
 <!--
-Thank you for your pull request. Please provide a description above and
-review the checklist below.
+Thank you for your pull request. 
+Please provide a description above and review the checklist below.
 
 Contributors guide: ./CONTRIBUTING.md
 -->
 
 ## Checklist
 <!--
-Remove items that do not apply. For completed items, change [ ] to [x] or you can click the checkboxes once your 
-pull-request is published.
+Remove items that do not apply. 
+For completed items, change [ ] to [x] or you can click the checkboxes once your pull-request is published.
 -->
 
 - [ ] Keep pull requests small so they can be easily reviewed.
-- [ ] Update the documentation, please follow the [numpy style guide](https://numpydoc.readthedocs.io/en/latest/format.html).
+- [ ] Update the documentation
+  - For in-code documentation, please follow the [numpy style guide](https://numpydoc.readthedocs.io/en/latest/format.html).
+  - For user documentation, please update the wiki in 
+    [`./activity_browser/docs/wiki`](https://github.com/LCA-ActivityBrowser/activity-browser/tree/main/activity_browser/docs/wiki)
 - [ ] Update tests.
+- [ ] Link this PR to related issues by using [closing keywords](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue).
+
+#### If you have write access (otherwise a maintainer will do this for you):
 - [ ] Categorize the PR by setting a good title and adding one of the labels:
       `bug`, `feature`, `ui`, `change`, `documentation`, `breaking`, `ci`
       as they show up in the changelog.
-- [ ] Link this PR to related issues by using [closing keywords](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue).
 - [ ] Add a milestone to the PR (and related issues, if any) for the intended release.
 - [ ] Request a review from another developer.
 

.github/scripts/update_wiki.sh

@@ -0,0 +1,49 @@
+#! /bin/sh
+
+# input variables:
+# $1: commit message
+# $2: GH token ${{ secrets.GITHUB_TOKEN }}
+
+# clone the current wiki git
+cd ..
+git clone https://github.com/$GITHUB_REPOSITORY.wiki.git
+# extract the .git folder and empty the wiki folder
+mkdir temp
+yes | cp -rf activity-browser.wiki/.git temp
+find activity-browser.wiki -mindepth 1 -delete
+# copy the (potentially new) content from the main repo and the wiki .git folder to wiki folder and delete temp folder
+yes | cp -rf activity-browser/activity_browser/docs/wiki/* activity-browser.wiki/
+yes | cp -rf temp/.git activity-browser.wiki/
+rm -rf temp
+cd activity-browser.wiki
+# check if changes were made
+grep -lr "link:[a-zA-Z0-9_.-]*.asciidoc.*" .| xargs -r sed -i "s/.asciidoc//g"
+if git diff-index --quiet HEAD && [ ! -n "$(git status -s)" ]; then
+  # no changes
+  echo "Wiki documentation was not changed, documentation, not updating."
+  # return folders to original state
+  cd ..
+  rm -rf activity-browser.wiki
+  cd activity-browser
+  # exit script
+  set +e
+  pkill -9 -P $$ &> /dev/null || true
+  exit 0
+else
+  # changes
+  echo "Wiki documentation was changed, documentation, updating."
+  # set github user
+  git config --global user.name "$GITHUB_ACTOR"
+  git config --global user.email "$(git log -n 1 --pretty=format:%ae)"
+  # commit changes to wiki git
+  git status
+  git add .
+  git commit -m "$1"
+  # create origin and push
+  git remote add origin-wiki "https://$GITHUB_ACTOR:$2@github.com/$GITHUB_REPOSITORY.wiki"
+  git push origin-wiki master
+  # return folders to original state
+  cd ..
+  rm -rf activity-browser.wiki
+  cd activity-browser
+fi

.github/workflows/install-canary.yaml

@@ -15,7 +15,7 @@ jobs:
       fail-fast: false
       matrix:
         os: [ubuntu-latest, windows-latest, macos-13]
-        python-version: ['3.8', '3.9', '3.10', '3.11']
+        python-version: ["3.10", "3.11"]
     defaults:
       run:
         shell: bash -l {0}
@@ -35,7 +35,7 @@ jobs:
           conda env export
           conda env export -f env.yaml
       - name: Upload final environment as artifact
-        uses: actions/upload-artifact@v3
+        uses: actions/upload-artifact@v4
         with:
           name: env-${{ matrix.os }}-${{ matrix.python-version }}
           path: env.yaml
@@ -66,7 +66,7 @@ jobs:
           micromamba env export
           micromamba env export > env.yaml
       - name: Upload final environment as artifact
-        uses: actions/upload-artifact@v3
+        uses: actions/upload-artifact@v4
         with:
           name: env-${{ matrix.os }}-${{ matrix.python-version }}-mamba
           path: env.yaml
@@ -81,7 +81,7 @@ jobs:
       - canary-installs-mamba
     steps:
       - name: Download all artifacts
-        uses: actions/download-artifact@v3
+        uses: actions/download-artifact@v4
       - name: show files
         run: |
           ls -la

.github/workflows/main.yaml

@@ -22,7 +22,7 @@ jobs:
       - name: Show patched environment
         run: cat patched-environment.yml
       - name: Upload patched environment as artifact
-        uses: actions/upload-artifact@v3
+        uses: actions/upload-artifact@v4
         with:
           name: patched-environment
           path: patched-environment.yml
@@ -41,7 +41,7 @@ jobs:
     steps:
       - uses: actions/checkout@v3
       - name: Download patched test environment
-        uses: actions/download-artifact@v3
+        uses: actions/download-artifact@v4
         with:
           name: patched-environment
       - name: Setup python ${{ matrix.python-version }} conda environment

.github/workflows/manual_update_wiki.yml

@@ -0,0 +1,12 @@
+name: manual update of wiki
+
+on:
+  workflow_dispatch:
+
+jobs:
+  update_wiki:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - name: update wiki
+        run: ./.github/scripts/update_wiki.sh "Manual wiki update for $GITHUB_REF_NAME" "${{ secrets.GITHUB_TOKEN }}"

.github/workflows/release.yaml

@@ -38,3 +38,5 @@ jobs:
         run: |
           anaconda -t ${{ secrets.CONDA_UPLOAD_TOKEN }} upload \
           /usr/share/miniconda/envs/build/conda-bld/noarch/*.tar.bz2
+      - name: Update wiki
+        run: ./.github/scripts/update_wiki.sh "Automated documentation update for $GITHUB_REF_NAME" "${{ secrets.GITHUB_TOKEN }}"

CONTRIBUTING.md

@@ -33,14 +33,31 @@ welcome!
 If you want to include the opening graphics created for the existing youtube videos, please 
 [contact the developers](https://github.com/LCA-ActivityBrowser/activity-browser#developers).
 
-### Github wiki page
+### Wiki
 The Activity Browser has its own
-[__wiki__](https://github.com/LCA-ActivityBrowser/activity-browser/wiki) page!
-This page contains an explanation (in text) of how to get started with the AB.
-
-Sadly, other than this, there is still very little to be found there. If you
-want to contribute to the wiki, either by adding figures or links or by writing
-new sections, please contact the developers!
+[__wiki__](https://github.com/LCA-ActivityBrowser/activity-browser/wiki).
+This page contains an explanation of how to get started with the AB.
+
+If you want to contribute to the wiki, either by adding figures or links or by writing
+new sections, please [contact the developers](https://github.com/LCA-ActivityBrowser/activity-browser#developers)! 
+
+#### Making changes to the wiki _(for developers)_
+Any images or other assets in the documentation should be stored in `docs/wiki/assets` and linked to there instead of 
+online links (unless copyrighted material is linked that cannot be shown in any other way). 
+This way all assets are stored in the wiki git.
+
+To make changes to the wiki, open a pull request with suggested changes to 
+[`docs/wiki`](https://github.com/LCA-ActivityBrowser/activity-browser/tree/main/activity_browser/docs/wiki).
+While contributors with write access to Activity Browser can directly change the wiki, <u>changes should instead be made
+to the files in `docs/wiki`</u> 
+([#1350](https://github.com/LCA-ActivityBrowser/activity-browser/pull/1350)).
+
+The wiki can be updated in of 2 ways:
+1. Merging a pull request and then manually
+[triggering the wiki update action](https://github.com/LCA-ActivityBrowser/activity-browser/actions/workflows/manual_update_wiki.yml).
+   - e.g. for fixing typos or making existing text clearer 
+2. When a new release is made, any changes will automatically be written to the wiki.
+   - e.g. for new text related to a new feature release, which should only be visible when the feature is available
 
 ### In-software guidance
 With more and more features being included into the AB, the inclusion of
@@ -198,9 +215,12 @@ When the tests pass on a pull-request, one of the maintainers of AB will review
 
 ### Do's and Don'ts
 - Please do document any new code you wish to include in the activity browser.
-  This means writing useful documentation in the code (please follow the 
-  [numpy style guide](https://numpydoc.readthedocs.io/en/latest/format.html)), but also writing useful tooltips, labels
-  and other things that can help users.
+  This means:
+  - Writing useful documentation in the code (please follow the 
+  [numpy style guide](https://numpydoc.readthedocs.io/en/latest/format.html)), 
+  - Writing useful tooltips, labels and other things that can help users in the software,
+  - Updating the wiki in 
+    [`./activity_browser/docs/wiki`](https://github.com/LCA-ActivityBrowser/activity-browser/tree/main/activity_browser/docs/wiki)
 - Where possible, avoid importing and using brightway2 classes and methods directly in the Qt application code. 
   If some complex data processing is needed, see if your use-case is covered by bwutils instead. 
   If bwutils does not contain any for your use-case you are welcome to add it.