Merge branch 'packaging' - early part (WIP)

* packaging:
  docs: Use MkDocs for documentation, deploy to GitHub Pages
  pyproject.toml: Unify formatting of [project.optional-dependencies]

.github/workflows/release.yml

@@ -0,0 +1,128 @@
+# Publish package on release branch if it's tagged with 'v*'
+
+name: build & release
+
+on:
+  # Triggers the workflow on push events but only for the 'main' branch
+  push:
+    branches: [ "main" ]
+    tags:
+      - 'v*'
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+# via this GitHub Action
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# NOTE: alternative would be to write to 'gh-pages' branch
+# which might be needed if we want to have documentation for multiple versions
+# https://squidfunk.github.io/mkdocs-material/publishing-your-site/
+#permissions:
+#  contents: write
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        python-versions: ["3.10"]
+
+    # map step outputs to job outputs so they can be share among jobs
+    outputs:
+      #package_version: ${{ steps.variables_step.outputs.package_version }}
+      #package_name: ${{ steps.variables_step.outputs.package_name }}
+      repo_name: ${{ steps.variables_step.outputs.repo_name }}
+      repo_owner: ${{ steps.variables_step.outputs.repo_owner }}
+
+    steps:
+      - name: Checkout project source code
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-versions }}
+          cache: pip
+
+      - name: Store the 'cache_id' environmental variable
+        run: |
+          echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
+
+      - name: Restore cached virtualenv
+        uses: actions/cache/restore@v4
+        with:
+          key: venv-${{ runner.os }}-${{ steps.setup_python.outputs.python-version }}-${{ hashFiles('requirements.txt') }}
+          path: .venv
+
+      - name: Install dependencies, using cached venv
+        run: |
+          # use [cached] virtual environment, see https://adamj.eu/tech/2023/11/02/github-actions-faster-python-virtual-environments/
+          python -m venv .venv
+          source .venv/bin/activate
+          # upgrade pip
+          python -m pip install --upgrade pip
+          # install the package and its dependencies; note: it could use requirements.txt
+          python -m pip install --editable .[dev,doc]
+          # add to $VIRTUAL_ENV/bin to $PATH to be able to run scripts
+          echo "$VIRTUAL_ENV/bin" >> $GITHUB_PATH
+          # add information about active virtual environment to environment variables
+          echo "VIRTUAL_ENV=$VIRTUAL_ENV" >> $GITHUB_ENV
+
+      - name: Saved cached virtualenv
+        uses: actions/cache/save@v4
+        with:
+          key: venv-${{ runner.os }}-${{ steps.setup_python.outputs.python-version }}-${{ hashFiles('requirements.txt') }}
+          path: .venv
+
+      - name: Declare variables for convenient use
+        id: variables_step
+        run: |
+          echo "repo_owner=${GITHUB_REPOSITORY%/*}" >> $GITHUB_OUTPUT
+          echo "repo_name=${GITHUB_REPOSITORY#*/}" >> $GITHUB_OUTPUT
+          #echo "package_name=`poetry version | awk '{print $1}'`" >> $GITHUB_OUTPUT
+          #echo "package_version=`poetry version --short`" >> $GITHUB_OUTPUT
+        shell: bash
+
+      - name: Configure Git Credentials
+        run: |
+          git config user.name github-actions[bot]
+          git config user.email 41898282+github-actions[bot]@users.noreply.github.com
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v5
+
+      - name: Build documentation
+        run: |
+          mkdocs build --site-dir public
+
+      - name: Upload documentation as artifact
+        id: deployment
+        uses: actions/upload-pages-artifact@v3
+        with:
+          name: documentation
+          path: public/
+
+  # Deployment job
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    runs-on: ubuntu-latest
+    needs: release
+    steps:
+      - name: Deploy documentation to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

docs/index.md

@@ -0,0 +1,3 @@
+{%
+    include-markdown "../README.md"
+%}

mkdocs.yml

@@ -0,0 +1,97 @@
+site_name: PatchScope Documentation
+site_url: https://ncusi.github.io/PatchScope
+repo_url: https://github.com/ncusi/PatchScope
+repo_name: PatchScope
+#strict: true
+nav:
+  - home: index.md
+  #- installation: installation.md
+  #- usage: usage.md
+  #- modules: api.md
+  #- contributing: contributing.md
+  #- authors: authors.md
+  #- history: history.md
+theme:
+  name: material
+  language: en
+  logo: favicon.png
+  palette:
+    - media: "(prefers-color-scheme: light)"
+      scheme: default
+      toggle:
+        icon: material/weather-night
+        name: Switch to dark mode
+    - media: "(prefers-color-scheme: dark)"
+      scheme: slate
+      toggle:
+        icon: material/weather-sunny
+        name: Switch to light mode
+  features:
+    - navigation.indexes
+    - navigation.tabs
+    - navigation.instant
+    - navigation.tabs.sticky
+markdown_extensions:
+  #- pymdownx.emoji:  # inserting emoji via simple short names, e.g. :thumbsup:
+  #    emoji_index: !!python/name:materialx.emoji.twemoji  # problems with materialx, ...
+  ## ERROR: Could not find a version that satisfies the requirement mkdocs-material-extension~=1.0.3;
+  ##        extra == "doc" (from patchscope[dev,doc]) (from versions: none)
+  ## ERROR: No matching distribution found for mkdocs-material-extension~=1.0.3; extra == "doc"
+  #    emoji_generator: !!python/name:material.extensions.emoji.to_svg  # problems with material.extensions
+  ## Error: MkDocs encountered an error parsing the configuration file: while constructing a Python object
+  ## cannot find module 'material.extensions.emoji' (No module named 'material.extensions')
+  ##   in "/home/runner/work/PatchScope/PatchScope/mkdocs.yml", line 36, column 20
+  #- pymdownx.critic  # editorial change tracking in plain text files
+  - pymdownx.caret  # ^^insert^^, text^superscript
+  #- pymdownx.mark  # ==mark me==
+  - pymdownx.tilde  # ~~delete~~, text~subscript
+  - pymdownx.tabbed  # tabbed contents
+  - pymdownx.arithmatex:  # block and inline block equations: $...$, $$...$$
+      generic: true
+  - pymdownx.highlight:  # syntax highlighting of code blocks (with superfences)
+      linenums: true
+  - pymdownx.superfences  #  arbitrary nesting of code and content blocks
+    #  custom_fences:
+    #    - name: mermaid
+    #      class: mermaid
+    #      format: !!python/name:pymdownx.superfences.fence_code_format
+  - pymdownx.details  # make admonition call-outs collapsible
+  - pymdownx.tasklist:  #  GitHub Flavored Markdown inspired task lists
+      custom_checkbox: true  # replace native checkbox styles with icons
+  - admonition  # admonitions (or call-outs), !!! note "optional title"...
+  - attr_list  # add HTML attributes and CSS classes to alnost every element
+  - toc:  # automatically generate a table of contents
+      baselevel: 2
+      permalink: true
+      slugify: !!python/name:pymdownx.slugs.uslugify
+  - meta
+plugins:
+  - include-markdown  # including (embedding) Markdown files, by default within {% and %}
+  - search:  # adds a search bar to the header; powered by lunr.js
+      lang: en
+  - mkdocstrings:  # automatic documentation from sources for MkDocs
+      watch:
+        - PatchScope
+#extra:
+#  version:
+#    provider: mike
+#  social:
+#    - icon: fontawesome/brands/twitter
+#      # replace with your own tweet link below
+#      link: http://www.jieyu.ai
+#      name: Tweet
+#    - icon: fontawesome/brands/facebook
+#      # replace with your own facebook link below
+#      link: http://www.jieyu.ai
+#      name: Facebook
+#    - icon: fontawesome/brands/github
+#      link: https://github.com/jnareb/python_project_wizard_demo
+#      name: Github
+#    - icon: material/email
+#      link: "mailto:[email protected]"
+#  # to enable disqus, uncomment the following and put your disqus id below
+#  # disqus: disqus_id
+# uncomment the following and put your google tracking id below to enable GA
+#google_analytics:
+  #- UA-xxx
+  #- auto

pyproject.toml

@@ -56,9 +56,26 @@ version = {attr = "diffannotator.config.__version__"}
 #
 # see: https://setuptools.pypa.io/en/latest/userguide/pyproject_config.html#dynamic-metadata
 [project.optional-dependencies]
-dev = ["pytest==8.3.4"]
-pylinguist = ["linguist@git+https://github.com/retanoj/linguist#egg=master"]
-examples = ["dvc[s3]==3.58.0"]  # dvc-s3 is needed to access 'dagshub' dvc remote
+dev = [
+  "pytest==8.3.4",
+]
+doc = [
+  "mkdocs~=1.2.3",
+  "mkdocs-include-markdown-plugin~=3.2.3",
+  "mkdocs-autorefs~=0.3.1",
+  "mkdocstrings~=0.18.0",
+  "mkdocs-material~=8.1.11",
+  #"mike~=1.1.2",
+  #"setuptools~=68.0",
+  #"pkginfo~=1.9",
+  #"virtualenv~=20.0",
+]
+pylinguist = [
+  "linguist@git+https://github.com/retanoj/linguist#egg=master",
+]
+examples = [
+  "dvc[s3]==3.58.0",
+]  # dvc-s3 is needed to access 'dagshub' dvc remote
 web = [
   "panel==1.5.4",
   "param==2.1.1",