WIP - Test the docs

Related to jazzband#526

Add a command to build the documentation using Sphinx and update the CI workflow to include a documentation build stage.

* **run.sh**
  - Add a command to build the documentation using Sphinx.
  - Update the usage function to include the new builddocs command.

* **.github/workflows/python-package.yml**
  - Add a new stage to run the documentation building to ensure it works.
  - Update the release-production stage to depend on the new docs stage.

.github/workflows/python-package.yml

@@ -105,13 +105,33 @@ jobs:
         run: |
           tox -e i18n
 
+  docs:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+      - uses: actions/cache@v4
+        with:
+          path: ~/.cache/pip
+          key: ${{ matrix.python-version }}-pip-${{ hashFiles('**/requirements.txt') }}
+          restore-keys: |
+            ${{ matrix.python-version }}-pip-
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install sphinx
+      - name: Build docs
+        run: |
+          ./run.sh builddocs
+
   release-production:
     # Only upload if a tag is pushed (otherwise just build & check)
     if: github.event_name == 'push' && startsWith(github.event.ref, 'refs/tags')
 
     runs-on: ubuntu-latest
 
-    needs: [test, lint, i18n]
+    needs: [test, lint, i18n, docs]
 
     steps:
       - uses: actions/checkout@v4

run.sh

@@ -10,6 +10,10 @@ usage() {
     echo "  typecheck - run mypy"
     echo "  shell - open the Django shell"
     echo "  makemigrations - create a schema migration"
+    echo "  makemessages - create message files for translation"
+    echo "  compilemessages - compile message files for translation"
+    echo "  find_uncommitted_translations - find uncommitted translation changes"
+    echo "  builddocs - build the documentation using Sphinx"
     exit 1
 }
 
@@ -33,6 +37,8 @@ case "$CMD" in
         export DJANGO_SETTINGS_MODULE= && cd waffle && django-admin compilemessages && cd - ;;
     "find_uncommitted_translations" )
         git diff --exit-code -G "^(msgid|msgstr)" || (echo "Please run ./run.sh makemessages and commit the updated django.po file." && false) ;;
+    "builddocs" )
+        sphinx-build -b html docs docs/_build ;;
     * )
         usage ;;
 esac