Fix docs build to use tox, as described

- Update tox.ini to use the correct
  dependencies file.
- Update the docs requirements file
  to remove stale dependencies.
- Update the GitHub workflow so that
  docs are built on a push to the
  default branch rather than on
  a schedule.

.github/workflows/docs-build.yaml

@@ -2,7 +2,7 @@ name: docs-build
 
 on:
   pull_request:
-    branches: [main]
+    branches: [ main ]
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.event.pull_request.number  || github.ref }}
@@ -24,11 +24,14 @@ jobs:
           python-version: ${{ matrix.python-version }}
       - name: Install dependencies
         run: |
-          python -m pip install --upgrade pip setuptools==59.4.0 wheel
-          python -m pip install -r docs/requirements-doc.txt
+          python -m pip install --upgrade pip tox
       - name: Building docs
         run: |
-          make -C docs html
+          tox -e docs
+      - name: Delete unnecessary files
+        run: |
+          find docs/build -name .doctrees -prune -exec rm -rf {} \;
+          find docs/build -name .buildinfo -exec rm -rf {} \;
       - name: Upload HTML
         uses: actions/upload-artifact@v3
         with:

.github/workflows/docs-sched-rebuild.yaml

@@ -1,9 +1,10 @@
 name: docs-sched-rebuild
 
 on:
-  schedule:
-    # * is a special character in YAML so you have to quote this string
-    - cron: "0 1 * * *"
+  push:
+    branches: [ main ]
+    tags:
+      - v*
   workflow_dispatch:
 
 jobs:
@@ -20,14 +21,10 @@ jobs:
           python-version: 3.9
       - name: Install dependencies
         run: |
-          python -m pip install --upgrade pip setuptools==59.4.0 wheel
-          python -m pip install -r docs/requirements-doc.txt
-      - name: Report the versions to build
-        run: |
-          sphinx-multiversion --dump-metadata docs/source docs/build/html | jq "keys"
+          python -m pip install --upgrade pip tox
       - name: Building docs (multiversion)
         run: |
-          sphinx-multiversion docs/source docs/build/html
+          tox -e docs-multi
       - name: Delete unnecessary files
         run: |
           find docs/build -name .doctrees -prune -exec rm -rf {} \;

docs/requirements-doc.txt

@@ -15,7 +15,6 @@ Markdown==3.3.7
 
 # smx
 mergedeep<1.4
-docker<5.1
 PyGithub<1.56
 semver>=2,<3
 pytest<7.3

tox.ini

@@ -13,7 +13,7 @@ commands =
 [testenv:test-gpu]
 passenv =
     OPAL_PREFIX
-setenv = 
+setenv =
     TF_GPU_ALLOCATOR=cuda_malloc_async
 sitepackages=true
 ; Runs in: Internal Jenkins
@@ -39,15 +39,14 @@ commands =
 ; Generates documentation with sphinx. There are other steps in the Github Actions workflow
 ; to publish the documentation on release.
 changedir = {toxinidir}
-deps = -rrequirements/docs.txt
+deps = -rdocs/requirements-doc.txt
 commands =
     python -m sphinx.cmd.build -E -P -b html docs/source docs/build/html
 
 [testenv:docs-multi]
 ; Run the multi-version build that is shown on GitHub Pages.
 changedir = {toxinidir}
-deps = -rrequirements/docs.txt
+deps = -rdocs/requirements-doc.txt
 commands =
     sphinx-multiversion --dump-metadata docs/source docs/build/html | jq "keys"
     sphinx-multiversion docs/source docs/build/html
-