Add Github Actions for testing major Sphinx versions (#62)

* test builds

* fix typos

* fix sphinx versions

* remove Python 3.8

* install `breathe`

* try installing piccolo_theme

* try installing wheel

* try `setup.py install`

* try with python

* only use breathe on Sphinx < 7

* remove query param from css file

* only show breathe docs on Sphinx < 7

* bump sphinx version used in docs

* try running playwright in CI

* use more recent GitHub actions

Author: dantownsend

.github/workflows/tests.yaml

@@ -0,0 +1,50 @@
+name: Test Suite
+
+on:
+    push:
+        branches: ["master"]
+    pull_request:
+        branches: ["master"]
+
+jobs:
+    test_sphinx:
+        runs-on: ubuntu-latest
+        strategy:
+            matrix:
+                python-version: ["3.9", "3.10", "3.11"]
+                sphinx-version: ["7.2.2", "6.2.1", "5.3.0"]
+
+        steps:
+            - uses: actions/checkout@v3
+            - name: Set up Python ${{ matrix.python-version }}
+              uses: actions/setup-python@v4
+              with:
+                  python-version: ${{ matrix.python-version }}
+            - name: Install Sphinx ${{ matrix.sphinx-version }}
+              run: |
+                  python -m pip install --upgrade pip
+                  pip install Sphinx==${{ matrix.sphinx-version }}
+            - name: Install breathe
+              run: pip install breathe==4.35.0
+            - name: Install wheel
+              run: pip install wheel
+            - name: Install piccolo_theme
+              run: python setup.py install
+            - name: Build docs
+              run: make html
+              working-directory: ./docs
+            - name: "Setup Node"
+              uses: actions/setup-node@v3
+              with:
+                node-version: 18
+            - name: Install Playwright
+              run: pip install -r requirements/e2e-requirements.txt
+            - name: Ensure Chromium is installed
+              run: python -m playwright install chromium --with-deps
+            - name: Start Playwright tests
+              run: ./scripts/run-e2e-tests.sh
+            - uses: actions/upload-artifact@v3
+              with:
+                name: playwright-artifacts
+                path: videos/
+              if: always()

.gitignore

@@ -5,3 +5,4 @@ dist/
 piccolo_theme.egg-info/
 build/
 docs/_build/
+videos/

docs/src/conf.py

@@ -13,6 +13,9 @@
 import datetime
 import os
 import sys
+
+import sphinx
+
 sys.path.insert(0, os.path.abspath('../..'))
 
 
@@ -31,7 +34,6 @@
 # ones.
 extensions = [
     'sphinx.ext.autodoc',
-    'breathe'
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -72,14 +74,25 @@
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = []
 
-breathe_projects = {
-    "cpp_demo": "./cpp_breathe_demo",
-    "c_demo": "./c_breathe_demo"
-}
-breathe_default_project = "cpp_demo"
-breathe_domain_by_extension = {
-    "h": "c",
-    "c": "c",
-    "hpp": "cpp",
-    "cpp": "cpp"
-}
+if sphinx.version_info[0] < 7:
+    # Breathe only works on certain Sphinx versions.
+
+    extensions.append('breathe')
+
+    breathe_projects = {
+        "cpp_demo": "./cpp_breathe_demo",
+        "c_demo": "./c_breathe_demo"
+    }
+    breathe_default_project = "cpp_demo"
+    breathe_domain_by_extension = {
+        "h": "c",
+        "c": "c",
+        "hpp": "cpp",
+        "cpp": "cpp"
+    }
+
+    # By using tags, we can exclude the breathe examples from the docs using
+    # the ``only`` directive.
+    tags.add('include_breathe')  # noqa  # type: ignore
+else:
+    tags.add('exclude_breathe')  # noqa  # type: ignore

docs/src/demo.rst

@@ -17,13 +17,19 @@ Autodoc
 Breathe
 -------
 
-.. doxygenclass:: CppClass
-    :members:
+.. only:: include_breathe
 
-.. doxygenfunction:: cpp_function
+  .. doxygenclass:: CppClass
+      :members:
 
-.. doxygenfunction:: c_function
-    :project: c_demo
+  .. doxygenfunction:: cpp_function
+
+  .. doxygenfunction:: c_function
+      :project: c_demo
+
+.. only:: exclude_breathe
+
+  We can't demo Breathe on this version of Sphinx.
 
 -------------------------------------------------------------------------------
 

e2e/README.rst

@@ -0,0 +1,32 @@
+e2e tests
+=========
+
+We use Playwright to make sure the theme works on multiple versions of Sphinx.
+
+It is run automatically in GitHub Actions.
+
+To run it locally:
+
+.. code-block:: bash
+
+    pip install -r requirements/e2e-requirements.txt
+    playwright install chromium
+
+Make sure the local docs have been built, as this is what we test against:
+
+.. code-block:: bash
+
+    cd docs
+    make html
+
+Then from the root of the project, run the Playwright tests:
+
+.. code-block:: bash
+
+    ./scripts/run-e2e-tests.sh
+
+You can see the tests run in the browser using the ``--headed`` flag:
+
+.. code-block:: bash
+
+    ./scripts/run-e2e-tests.sh --headed

e2e/conftest.py

@@ -0,0 +1,69 @@
+import os
+import time
+from http.client import HTTPConnection
+from subprocess import PIPE, Popen
+
+import pytest
+
+
+HOST = "localhost"
+PORT = 8000
+BASE_URL = f"http://{HOST}:{PORT}"
+DOCS_DIRECTORY = os.path.join(
+    os.path.dirname(os.path.dirname(__file__)), "docs", "build", "html"
+)
+
+
+@pytest.fixture
+def browser_context_args():
+    return {"record_video_dir": "videos/"}
+
+
+@pytest.fixture
+def context(context):
+    # We don't need a really long timeout.
+    # The timeout determins how long Playwright waits for a HTML element to
+    # become available.
+    # By default it's 30 seconds, which is way too long when testing an app
+    # locally.
+    context.set_default_timeout(5000)
+    yield context
+
+
+@pytest.fixture(autouse=True)
+def dev_server():
+    """
+    Running dev server and Playwright test in parallel.
+    More info https://til.simonwillison.net/pytest/playwright-pytest
+    """
+    process = Popen(
+        [
+            "python3",
+            "-m",
+            "http.server",
+            "--bind",
+            str(HOST),
+            "--directory",
+            DOCS_DIRECTORY,
+            str(PORT),
+        ],
+        stdout=PIPE,
+    )
+    retries = 5
+    while retries > 0:
+        conn = HTTPConnection(f"{HOST}:{PORT}")
+        try:
+            conn.request("HEAD", "/")
+            response = conn.getresponse()
+            if response is not None:
+                yield process
+                break
+        except ConnectionRefusedError:
+            time.sleep(1)
+            retries -= 1
+
+    if not retries:
+        raise RuntimeError("Failed to start http server")
+    else:
+        process.terminate()
+        process.wait()

e2e/test_homepage.py

@@ -1,9 +1,12 @@
 import re
+
 from playwright.sync_api import Page, expect
 
+from conftest import BASE_URL
+
 
 def test_homepage(page: Page):
-    page.goto("http://localhost:8000/")
+    page.goto(BASE_URL)
     # Expect a title "to contain" a substring.
     expect(page).to_have_title(re.compile("Piccolo Theme"))
 
@@ -18,28 +21,28 @@ def test_homepage(page: Page):
         'https://github.com/piccolo-orm/piccolo_theme/'))
 
     # Dark Mode
-    page.goto("http://localhost:8000/")
+    page.goto(BASE_URL)
     expect(page.locator('html')).to_have_attribute("data-mode", "light")
     page.locator("#mode_toggle").click()
     expect(page.locator('html')).to_have_attribute("data-mode", "dark")
     page.locator("#mode_toggle").click()
     expect(page.locator('html')).to_have_attribute("data-mode", "darkest")
 
     # Search for Configuration
-    page.goto("http://localhost:8000/")
+    page.goto(BASE_URL)
     page.locator(
         '//*[@id="searchbox"]/div/form/input[1]').fill("Configuration")
     page.locator('//*[@id="searchbox"]/div/form/input[2]').click()
     expect(page).to_have_title(re.compile("Search"))
 
     # Check external Sphinx Link
-    page.goto("http://localhost:8000/")
+    page.goto(BASE_URL)
     link = page.locator('//*[@id="piccolo-theme"]/p/a')
     expect(link).to_have_text("Sphinx")
     expect(link).to_have_attribute(
         "href", "https://www.sphinx-doc.org/en/master/")
 
     # Link Check Setup
-    page.goto("http://localhost:8000/")
+    page.goto(BASE_URL)
     page.locator('//*[@id="piccolo-theme"]/div/ul/li[1]/a').click()
     expect(page).to_have_title(re.compile("Setup"))

piccolo_theme/theme.conf

@@ -1,6 +1,6 @@
 [theme]
 inherit = basic
-stylesheet = basic_mod.css?v=0.7.0-1
+stylesheet = basic_mod.css
 pygments_style = default
 sidebars = globaltoc.html
 

requirements/doc-requirements.txt

@@ -1,3 +1,3 @@
-Sphinx==6.1.3
+Sphinx==6.2.1
 sphinx-autobuild==2021.3.14
 breathe==4.35.0

requirements/e2e-requirements.txt

@@ -0,0 +1,2 @@
+pytest==7.4.0
+pytest-playwright==0.4.2