docs: use new documentation builder and layout

.github/workflows/docs.yaml

@@ -1,59 +1,29 @@
 name: Docs
 
 on:
-    push:
-        branches: [main]
-    release:
-        types: [released]
-    pull_request:
-        types: [opened, synchronize]
+  push:
+    branches: [main]
+  release:
+    types: [released]
+  pull_request:
+    types: [opened, synchronize]
 
 jobs:
-    docs:
-        runs-on: ubuntu-latest
-        permissions:
-          contents: write
+  docs:
+    runs-on: ubuntu-latest
 
-        steps:
-        - uses: actions/checkout@v3
+    permissions:
+      contents: write
 
-        - name: Setup Python
-          uses: actions/setup-python@v4
-          with:
-              python-version: "3.10"
+    steps:
+    - uses: actions/checkout@v4
 
-        - name: Install Dependencies
-          run: |
-            python -m pip install --upgrade pip
-            pip install .[doc]
+    - name: Setup Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: "3.10"
 
-        - name: Build HTML artifact
-          run: python build_docs.py
-
-        - name: Upload HTML artifact
-          uses: actions/upload-artifact@v3
-          with:
-              name: DocumentationHTML
-              path: docs/_build/silverback
-
-        - name: Commit and publish documentation changes to gh-pages branch
-          run: |
-              if [[ "${GITHUB_EVENT_NAME}" =~ "pull_request" ]]; then
-                echo "skipping 'git commit' step for PR"
-              else
-                git clone https://github.com/${GITHUB_REPOSITORY} --branch gh-pages --single-branch gh-pages
-                cp -r docs/_build/silverback/* gh-pages/
-                cd gh-pages
-                touch .nojekyll
-                git config --local user.email "[email protected]"
-                git config --local user.name "GitHub Action"
-                git add .
-                git commit -m "Update documentation" -a || true
-              fi
-        - name: Push changes
-          uses: ad-m/github-push-action@master
-          if: ${{ github.event_name != 'pull_request' }}
-          with:
-              branch: gh-pages
-              directory: gh-pages
-              github_token: ${{ secrets.GITHUB_TOKEN }}
+    - name: Ape Docs
+      uses: apeworx/sphinx-ape@main
+      with:
+        github-token: ${{ secrets.GITHUB_TOKEN }}

CONTRIBUTING.md

@@ -32,6 +32,34 @@ pre-commit install
 
 Committing will now automatically run the local hooks and ensure that your commit passes all lint checks.
 
+## Running the docs locally
+
+First, make sure you have the docs-related tooling installed:
+
+```bash
+pip install -e .'[doc]'
+```
+
+Then, run the following from the root project directory:
+
+```bash
+sphinx-ape build .
+```
+
+For the best viewing experience, use a local server:
+
+```bash
+sphinx-ape serve .
+```
+
+Then, open your browser to `127.0.0.1:1337` and click the `ape` directory link.
+
+You can also use the `--open` flag to automatically open the docs:
+
+```bash
+sphinx-ape serve . --open
+```
+
 ## Pull Requests
 
 Pull requests are welcomed! Please adhere to the following: