docs: use new documentation builder, theme, and action (#2269)

.github/workflows/docs.yaml

@@ -1,72 +1,34 @@
 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
+  docs:
+    runs-on: ubuntu-latest
 
-        permissions:
-          contents: write
+    permissions:
+      contents: write
 
-        steps:
-        - uses: actions/checkout@v4
+    steps:
+    - uses: actions/checkout@v4
 
-        - name: Setup Python
-          uses: actions/setup-python@v5
-          with:
-              python-version: "3.10"
+    - name: Setup Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: "3.10"
 
-        - name: Install Dependencies
-          run: |
-            python -m pip install --upgrade pip
-            pip install .[doc]
+    - name: Install Dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install .[doc]
 
-        - name: Build HTML artifact
-          run: python build_docs.py
-
-        - name: Upload HTML artifact
-          uses: actions/upload-artifact@v4
-          with:
-              name: DocumentationHTML
-              path: docs/_build/ape
-
-        - name: Doctesting
-          run: |
-            sphinx-build -b doctest docs docs/_build/doctest
-            if grep -q '0 failed' docs/_build/doctest/output.txt; then
-              echo "All doctests passed!"
-            else
-              echo "Some doctests failed. See the output below."
-              cat docs/_build/doctest/output.txt
-              exit 1
-            fi
-
-        - 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/ape/* 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

@@ -58,19 +58,21 @@ pip install -e .'[doc]'
 Then, run the following from the root project directory:
 
 ```bash
-python build_docs.py
+sphinx-ape build .
 ```
 
 For the best viewing experience, use a local server:
 
 ```bash
-python -m http.server --directory "docs/_build/" --bind 127.0.0.1 1337
+sphinx-ape serve .
 ```
 
 Then, open your browser to `127.0.0.1:1337` and click the `ape` directory link.
 
-```{note}
-Serving from `"docs/_build/"` rather than `"docs/_build/ape"` is necessary to make routing work.
+You can also use the `--open` flag to automatically open the docs:
+
+```bash
+sphinx-ape serve . --open
 ```
 
 ## Pull Requests