docs: new documentation with mkdocs

.github/workflows/deploy_docs.yml

@@ -1,50 +1,17 @@
 name: deploy docs
 
 on:
-  # Trigger the workflow on push to main branch
   push:
     branches:
       - main
-    tags:
-      - 'v*' # Push events to matching v*, i.e. v1.0, v20.15.10
 
-# This job installs dependencies, builds the book, and pushes it to `gh-pages`
 jobs:
-  build-and-deploy-book:
-    runs-on: ubuntu-latest
+  deploy:
+    runs-on: macos-latest  # for the screenshots
     steps:
       - uses: actions/checkout@v3
-
-      # Install dependencies
-      - name: Set up Python 3.9
-        uses: actions/setup-python@v4
-        with:
-          python-version: 3.9
-      - name: Install Libraries
-        run: |
-          sudo apt-get install -y libdbus-1-3 libxkbcommon-x11-0 libxcb-icccm4 \
-            libxcb-image0 libxcb-keysyms1 libxcb-randr0 libxcb-render-util0 \
-            libxcb-xinerama0 libxcb-xinput0 libxcb-xfixes0 xvfb
-          /sbin/start-stop-daemon --start --quiet --pidfile /tmp/custom_xvfb_99.pid \
-            --make-pidfile --background --exec /usr/bin/Xvfb -- :99 \
-            -screen 0 1920x1200x24 -ac +extension GLX
-      - name: Install dependencies
-        run: |
-          pip install --upgrade pip
-          pip install .[pyqt5]
-          pip install -r docs/requirements.txt
-          python docs/patch.py
-
-      # Build the book
-      - name: Build the book
-        run: jupyter-book build docs
-        env:
-          DISPLAY: ":99.0"
-          XDG_RUNTIME_DIR: "/tmp/runtime-runner"
-
-      # Deploy the book's HTML to gh-pages branch
-      - name: GitHub Pages action
-        uses: peaceiris/actions-gh-pages@v3
+      - uses: actions/setup-python@v4
         with:
-          github_token: ${{ secrets.GITHUB_TOKEN }}
-          publish_dir: docs/_build/html
+          python-version: '3.11'
+      - run: pip install -e .[docs]
+      - run: mkdocs gh-deploy --strict --force

.gitignore

@@ -134,3 +134,4 @@ dmypy.json
 .DS_Store
 examples/_wip
 .ruff_cache
+docs/_images/

.pre-commit-config.yaml

@@ -14,7 +14,7 @@ repos:
 
 
   - repo: https://github.com/charliermarsh/ruff-pre-commit
-    rev: v0.0.245
+    rev: v0.0.247
     hooks:
       - id: ruff
         args: ["--fix"]

README.md

@@ -93,4 +93,4 @@ and usage examples.
 
 Contributions are welcome!
 
-See contributing guide [here](https://github.com/pyapp-kit/magicgui/blob/main/CONTRIBUTING.md).
+See contributing guide [here](https://github.com/pyapp-kit/magicgui/blob/main/docs/CONTRIBUTING.md).

CONTRIBUTING.md → docs/CONTRIBUTING.md

@@ -102,3 +102,20 @@ For more complex cases, you can add a new conditional to the body of the
 `match_type` function.  That function should always return a tuple of widget
 type, and kwargs that will be passed to the widget constructor. For example:
 `return widgets.MyNewWidget, {}`.
+
+### Building the documentation
+
+To build the documentation locally, you will need to install the `docs` extra:
+
+```bash
+pip install -e .[docs]
+```
+
+Then, from the root of the repository, run:
+
+```bash
+mkdocs serve
+```
+
+This will start a local server at `http://127.0.0.1:8000/` where you can view
+the documentation as you edit it.