docs: initial mkdocs

.github/workflows/cicd.yaml

@@ -172,6 +172,20 @@ jobs:
           token: ${{ secrets.GITHUB_TOKEN }}
           tag: "internal"
 
+  test-documentation:
+    name:  Test documentation build
+    runs-on: ubuntu-22.04
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+          cache: "pip"
+      - name: Install hatch
+        run: pip install hatch
+      - name: Build documentation
+        run: hatch run build-docs
+
   coveralls:
     name: Upload coverage
     needs: test
@@ -299,8 +313,16 @@ jobs:
     runs-on: ubuntu-22.04
     steps:
       - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+          cache: "pip"
+      - name: Install hatch
+        run: pip install hatch
+      - name: Build documentation
+        run: hatch run build-docs
       - name: Deploy pages
         uses: peaceiris/actions-gh-pages@v3
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
-          publish_dir: ./docs
+          publish_dir: ./site

.gitignore

@@ -34,6 +34,7 @@ coverage.xml
 .coveralls.yml
 .envrc
 
+
 ### Python ###
 # Byte-compiled / optimized / DLL files
 __pycache__/

.pre-commit-config.yaml

@@ -11,7 +11,7 @@ repos:
     rev: v4.5.0
     hooks:
       - id: check-ast
-      - id: check-yaml
+      #- id: check-yaml
       - id: check-toml
       - id: end-of-file-fixer
         exclude: ".srt$"
@@ -21,7 +21,7 @@ repos:
   - repo: local
     hooks:
       - id: check
-        name: run project checks
+        name: hatch run pre-commit
         stages: [commit]
         language: system
         entry: hatch run pre-commit

README.md

@@ -125,14 +125,14 @@ C:\Users\<USERNAME>\AppData\Local\Programs\Tesseract-OCR
   "New..." → Variable: `TESSDATA_PREFIX`, Value: `"C:\Program Files\Tesseract-OCR"`
 
 - Append Tesseract's base folder to the environment variable `PATH`, e.g.: "System
-  Properties" → Tab "Advanced" → "Environment Variables..." → Section "User variables" →
-  Select `PATH` → "Edit..." → Add a new entry `"C:\Program Files\Tesseract-OCR"`
+  Properties" → Tab "Advanced" → "Environment Variables..." → Section "User variables"
+  → Select `PATH` → "Edit..." → Add a new entry `"C:\Program Files\Tesseract-OCR"`
 
 - To test your setup, open a new `cmd`-terminal and run:
 
-  ```cmd
-  tesseract --list-langs
-  ```
+    ```cmd
+    tesseract --list-langs
+    ```
 
 4\. Install and run NormCap:
 
@@ -214,3 +214,11 @@ If NormCap doesn't fit your needs, try those alternatives (no particular order):
 ## Certification
 
 ![WOMM](https://raw.githubusercontent.com/dynobo/lmdiag/master/badge.png)
+
+## Contributors
+
+<a href="https://github.com/dynobo/normcap/graphs/contributors">
+  <img src="https://contrib.rocks/image?repo=dynobo/normcap" />
+</a>
+
+Made with [contrib.rocks](https://contrib.rocks).

adr/001-choose-transparent-windows-as-main-gui.md

@@ -42,8 +42,8 @@ switching to PySide6.
 
 - "Live-view" of the desktop (e.g. videos keep playing), which provides a better UX.
 - No need for acquiring the screenshots _before_ region selection.
-  - Slightly faster startup
-  - Better UX on Gnome 41+, where the screenshot has to be confirmed.
+    - Slightly faster startup
+    - Better UX on Gnome 41+, where the screenshot has to be confirmed.
 
 ### Negative Consequences
 

adr/003-use-system-tray-as-main-application.md

@@ -34,8 +34,8 @@ in full-screen.
 
 - Enables showing real full-screens on macOS
 - Better code maintenance
-  - Get rid of main_window + base_window in favor of a single type of window
-  - Better separation between application logic (in tray) and GUI
+    - Get rid of main_window + base_window in favor of a single type of window
+    - Better separation between application logic (in tray) and GUI
 
 ### Negative Consequences
 
@@ -57,8 +57,8 @@ in full-screen.
 
 - Good, because using the system tray as the main application, solves the black
   full-screen of the status quo on macOS: _create_ windows for selection, then _close_
-  (destroy) them immediately. Stay in tray either until the processing finished or until
-  the user closes the system tray (in case of "show in tray" is active).
+  (destroy) them immediately. Stay in tray either until the processing finished or
+  until the user closes the system tray (in case of "show in tray" is active).
 - Bad, because the system tray is necessary, even if "stay in tray" is not active. In
   that case, the system tray just get's closed again immediately after processing the
   OCR.

adr/004-do-not-implement-hotkey.md

@@ -110,8 +110,8 @@ of the other options A, B and C.
 - Bad, because changing system settings from within NormCap is risky: it can have
   unwanted side effects or cause issues if done wrong.
 - Bad, because the implementation effort is high, as NormCap has to implement it for all
-  platforms. On Linux, often the desktop environment is responsible for the hotkeys, so
-  at least supporting KDE and GNOME would be required, others would be desirable as
+  platforms. On Linux, often the desktop environment is responsible for the hotkeys,
+  so at least supporting KDE and GNOME would be required, others would be desirable as
   well.
 - Bad, because it increases maintenance efforts. Especially the Linux DEs are subject of
   changes, which might require adjusting the implementation in NormCap, with all the

adr/005-use-hatch-instead-poetry.md

@@ -12,11 +12,12 @@ this works quite well, there are some reoccurring pain points:
 
 - The scripting capabilities
   [are limited](https://python-poetry.org/docs/pyproject#scripts).
-  - This led to duplicate implementations of tasks like formatting, linting, testing and
-    l10n for pre-commit hooks and for the GitHub actions.
-  - There are currently multiple entry points for various different tasks, e.g. Python
-    package (`poetry build`), Briefcase package (`/bundle/build.py`, babel (`l10n.py`),
-    running normcap (script `normcap`), which increases cognitive overhead.
+    - This led to duplicate implementations of tasks like formatting, linting, testing and
+      l10n for pre-commit hooks and for the GitHub actions.
+    - There are currently multiple entry points for various different tasks, e.g. Python
+      package (`poetry build`), Briefcase package (`/bundle/build.py`, babel
+      (`l10n.py`), running normcap (script `normcap`), which increases cognitive
+      overhead.
 - Dependency resolution can be quite slow
 - Poetry does not follow PEP standards (however, no problem so far)
 
@@ -48,9 +49,9 @@ management, otherwise complexity would not be reduced.
 ### Positive Consequences
 
 - Reduced complexity:
-  - Use `hatch` as _one_ tool for most tasks `poetry` supported _as well as_ simple task
-    runner.
-  - Single entrypoint to tasks (`hatch run ...`)
+    - Use `hatch` as _one_ tool for most tasks `poetry` supported _as well as_ simple task
+      runner.
+    - Single entrypoint to tasks (`hatch run ...`)
 - Less maintenance effort because of less duplicated code for tasks.
 - `hatch` was adopted by PyPA and therefore is future-proof and well-supported.
 - Testing a new tool (learning opportunity).
@@ -59,27 +60,28 @@ management, otherwise complexity would not be reduced.
 
 - Implementation effort for transition.
 - Some integration efforts (e.g. venv activation via
-  [direnv](https://github.com/direnv/direnv) with 3rd party `layout hatch` to be used in
-  `zsh` and VSCode). Hopefully, this situation will improve over the time!
+  [direnv](https://github.com/direnv/direnv) with 3rd party `layout hatch` to be used
+  in `zsh` and VSCode). Hopefully, this situation will improve over the time!
 - New tool (learning efforts).
 
 ### Neutral
 
 - `hatch` does not yet support dependency locking. This is a minor issue, because:
-  - A locking feature might be added to `hatch` in midterm (needs some PEP-work, which
-    already started).
-  - Freezing is supported via 3rd party plugin
-    [hatch-pip-deepfreeze](https://github.com/sbidoul/hatch-pip-deepfreeze).
-  - In NormCap, currently the only dependencies are `PySide6` & `shiboken6`. They are
-    pinned to specific versions anyway and don't have any child-dependencies themselves.
-  - For development dependencies this is an issue, but the impact of potential problems
-    is minor.
+    - A locking feature might be added to `hatch` in midterm (needs some PEP-work, which
+      already started).
+    - Freezing is supported via 3rd party plugin
+      [hatch-pip-deepfreeze](https://github.com/sbidoul/hatch-pip-deepfreeze).
+    - In NormCap, currently the only dependencies are `PySide6` & `shiboken6`. They are
+      pinned to specific versions anyway and don't have any child-dependencies
+      themselves.
+    - For development dependencies this is an issue, but the impact of potential problems
+      is minor.
 - It's unclear, if the scripting support is good enough to ease all required tasks.
-  - If this _is_ the case, it would be a positive consequence, as more powerful tools
-    like `nox` would bring in more complexity and onboarding efforts.
-  - If this is _not_ the case, then it would have negative consequences, because the
-    complexity would again grow because of workarounds or bringing in a task runner as
-    additional tool.
+    - If this _is_ the case, it would be a positive consequence, as more powerful tools
+      like `nox` would bring in more complexity and onboarding efforts.
+    - If this is _not_ the case, then it would have negative consequences, because the
+      complexity would again grow because of workarounds or bringing in a task runner as
+      additional tool.
 
 ## Pros and Cons of the Options
 
@@ -130,17 +132,18 @@ individual developer. (For building, this is probably not a good idea.)
 - Neutral, as dependency locking is currently not PEP compliant and therefore not
   integrate into `hatch` core. However, this is subject to change, and until it is
   change the 3rd party plugin
-  [hatch-pip-deepfreeze](https://github.com/sbidoul/hatch-pip-deepfreeze) could be used.
+  [hatch-pip-deepfreeze](https://github.com/sbidoul/hatch-pip-deepfreeze) could be
+  used.
 - Neutral, as it has better scripting capabilities than `poetry`, but is way less
-  flexible than task runners like `nox`. Currently, it is unclear, if those capabilities
-  are really needed.
+  flexible than task runners like `nox`. Currently, it is unclear, if those
+  capabilities are really needed.
 - Bad, because of implementation efforts during the transition.
 - Bad, because it is (not yet) as widely adopted and therefore less well integrated.
   E.g. it takes more effort to get the following things to work:
-  - Auto-activation of environment in `zsh`.
-  - Auto-activation of environment in VSCode.
-  - Caching of environments in GitHub actions. (Caching with `poetry` is integrated in
-    the official `actions/setup-python`.)
+    - Auto-activation of environment in `zsh`.
+    - Auto-activation of environment in VSCode.
+    - Caching of environments in GitHub actions. (Caching with `poetry` is integrated in
+      the official `actions/setup-python`.)
 
 ## References
 

adr/006-use-jeepney-for-dbus-calls.md

@@ -62,11 +62,11 @@
   topics, few tutorials)
 - Bad, as relatively cumbersome to develop with, due to its lower level nature.
 - Bad, because it has significant number of flaws/bugs, e.g.:
-  - Can't send `u` (int32) datatype, as required for the window ID when using
-    `org.gnome.Shell.Extensions.Window`. See
-    [#PYSIDE-1904](https://bugreports.qt.io/browse/PYSIDE-1904).
-  - Can't reliably
-    [decode arguments](https://github.com/dynobo/normcap/blob/d79ef9c1c9ca022066944563c65290ccaadf6a45/normcap/screengrab/dbus_portal.py#L140-L161).
+    - Can't send `u` (int32) datatype, as required for the window ID when using
+      `org.gnome.Shell.Extensions.Window`. See
+      [#PYSIDE-1904](https://bugreports.qt.io/browse/PYSIDE-1904).
+    - Can't reliably
+      [decode arguments](https://github.com/dynobo/normcap/blob/d79ef9c1c9ca022066944563c65290ccaadf6a45/normcap/screengrab/dbus_portal.py#L140-L161).
 
 ### (B) Switch back to jeepney