Repository: enthought/traits-futures (language: python)

Issue:
Pin Sphinx version for CI documentation builds
The documentation build failed for the CI in #455, due to a new bug in the most recent Sphinx release 4.1.2.

We're hitting Sphinx bugs often enough that I think we should just pin the Sphinx version, at least for the CI documentation builds. The autodoc mocking in Sphinx appears to be particularly unstable.


Discussion / hints:

Fix patch:
diff --git a/.github/workflows/build-docs.yml b/.github/workflows/build-docs.yml
index 2fbf480c..53062c3c 100644
--- a/.github/workflows/build-docs.yml
+++ b/.github/workflows/build-docs.yml
@@ -26,8 +26,7 @@ jobs:
     - name: Install dependencies and local packages
       run: |
         python -m pip install --upgrade pip setuptools wheel
-        python -m pip install sphinx enthought-sphinx-theme
-        python -m pip install .
+        python -m pip install .[docs]
     - name: Build HTML documentation with Sphinx
       run: |
         cd docs
diff --git a/setup.py b/setup.py
index f6d3e531..0753599e 100644
--- a/setup.py
+++ b/setup.py
@@ -49,7 +49,7 @@ def get_long_description():
     extras_require={
         "pyqt5": ["pyqt5"],
         "pyside2": ["pyside2"],
-        "docs": ["enthought-sphinx-theme", "sphinx>=3.5"],
+        "docs": ["enthought-sphinx-theme", "sphinx>=3.5,<4"],
     },
     packages=find_packages(exclude=["ci"]),
     classifiers=[


Test patch:
diff --git a/.github/workflows/test-docs.yml b/.github/workflows/test-docs.yml
index 4e6b79b5..e18ed089 100644
--- a/.github/workflows/test-docs.yml
+++ b/.github/workflows/test-docs.yml
@@ -22,12 +22,11 @@ jobs:
     - name: Install necessary Python packages
       run: |
         python -m pip install --upgrade pip setuptools wheel
-        python -m pip install sphinx enthought-sphinx-theme
     - name: Check out the PR branch
       uses: actions/checkout@v2
-    - name: Install local package
+    - name: Install local package and documentation dependencies
       run: |
-        python -m pip install .
+        python -m pip install .[docs]
     - name: Build HTML documentation
       run: |
         cd docs