Tests: Update Sphinx test matrix for EmbedAPI (#10655)

humitos · web-flow · commit 751fc9909f07 · 2023-08-22T23:55:44.000+02:00
* Tests: Update Sphinx test matrix for EmbedAPI

- Test only the latest minor version of each major version
- Add newer versions we weren't testing

* Run without migrations to speed things up

* Update tests to work with Sphinx 7.x

* Lint

* Make explicit it requires Tox&lt;4
diff --git a/.circleci/config.yml b/.circleci/config.yml
@@ -34,6 +34,7 @@ jobs:
       - run: git submodule sync
       - run: git submodule update --init
       - run: pip install --user 'tox<4'
+      - run: tox --version
       - run: tox -c tox.embedapi.ini
 
   checks:
diff --git a/readthedocs/embed/v3/tests/test_external_pages.py b/readthedocs/embed/v3/tests/test_external_pages.py
@@ -5,7 +5,7 @@
 from django.urls import reverse
 from packaging.version import Version
 
-from .utils import srcdir
+from .utils import get_anchor_link_title, srcdir
 
 
 @pytest.mark.django_db
@@ -36,11 +36,7 @@ def test_default_main_section(self, app, client, requests_mock):
         response = client.get(self.api_url, params)
         assert response.status_code == 200
 
-        # https://github.com/sphinx-doc/sphinx/commit/bc635627d32b52e8e1381f23cddecf26429db1ae
-        if sphinx.version_info < (5, 0, 0):
-            title = "Permalink to this headline"
-        else:
-            title = "Permalink to this heading"
+        title = get_anchor_link_title("heading")
 
         # The output is different because docutils is outputting this,
         # and we're not sanitizing it, but just passing it through.
@@ -70,11 +66,7 @@ def test_specific_identifier(self, app, client, requests_mock):
         response = client.get(self.api_url, params)
         assert response.status_code == 200
 
-        # https://github.com/sphinx-doc/sphinx/commit/bc635627d32b52e8e1381f23cddecf26429db1ae
-        if sphinx.version_info < (5, 0, 0):
-            title = "Permalink to this headline"
-        else:
-            title = "Permalink to this heading"
+        title = get_anchor_link_title("heading")
 
         if Version(docutils.__version__) >= Version("0.17"):
             content = f'<section id="sub-title">\n<h2>Sub-title<a class="headerlink" href="https://docs.project.com#sub-title" title="{title}">¶</a></h2>\n<p>This is a reference to <a class="reference internal" href="https://docs.project.com#sub-title"><span class="std std-ref">Sub-title</span></a>.</p>\n</section>'
@@ -102,12 +94,14 @@ def test_dl_identifier(self, app, client, requests_mock):
         response = client.get(self.api_url, params)
         assert response.status_code == 200
 
+        title = get_anchor_link_title("definition")
+
         if sphinx.version_info < (3, 5, 0):
-            content = '<dt id="confval-config1">\n<code class="sig-name descname">config1</code><a class="headerlink" href="https://docs.project.com/configuration.html#confval-config1" title="Permalink to this definition">¶</a></dt>'
+            content = f'<dt id="confval-config1">\n<code class="sig-name descname">config1</code><a class="headerlink" href="https://docs.project.com/configuration.html#confval-config1" title="{title}">¶</a></dt>'
         elif sphinx.version_info[:2] == (3, 5):
-            content = '<dt id="confval-config1">\n<code class="sig-name descname"><span class="pre">config1</span></code><a class="headerlink" href="https://docs.project.com/configuration.html#confval-config1" title="Permalink to this definition">¶</a></dt>'
+            content = f'<dt id="confval-config1">\n<code class="sig-name descname"><span class="pre">config1</span></code><a class="headerlink" href="https://docs.project.com/configuration.html#confval-config1" title="{title}">¶</a></dt>'
         else:
-            content = '<dt class="sig sig-object std" id="confval-config1">\n<span class="sig-name descname"><span class="pre">config1</span></span><a class="headerlink" href="https://docs.project.com/configuration.html#confval-config1" title="Permalink to this definition">¶</a></dt>'
+            content = f'<dt class="sig sig-object std" id="confval-config1">\n<span class="sig-name descname"><span class="pre">config1</span></span><a class="headerlink" href="https://docs.project.com/configuration.html#confval-config1" title="{title}">¶</a></dt>'
 
         assert response.json() == {
             "url": "https://docs.project.com/configuration.html#confval-config1",
@@ -131,12 +125,14 @@ def test_dl_identifier_doctool_sphinx(self, app, client, requests_mock):
         response = client.get(self.api_url, params)
         assert response.status_code == 200
 
+        title = get_anchor_link_title("definition")
+
         if sphinx.version_info < (3, 5, 0):
-            content = '<dt id="confval-config1">\n<code class="sig-name descname">config1</code><a class="headerlink" href="https://docs.project.com/configuration.html#confval-config1" title="Permalink to this definition">¶</a></dt>'
+            content = f'<dt id="confval-config1">\n<code class="sig-name descname">config1</code><a class="headerlink" href="https://docs.project.com/configuration.html#confval-config1" title="{title}">¶</a></dt>'
         elif sphinx.version_info[:2] == (3, 5):
-            content = '<dt id="confval-config1">\n<code class="sig-name descname"><span class="pre">config1</span></code><a class="headerlink" href="https://docs.project.com/configuration.html#confval-config1" title="Permalink to this definition">¶</a></dt>'
+            content = f'<dt id="confval-config1">\n<code class="sig-name descname"><span class="pre">config1</span></code><a class="headerlink" href="https://docs.project.com/configuration.html#confval-config1" title="{title}">¶</a></dt>'
         else:
-            content = '<dt class="sig sig-object std" id="confval-config1">\n<span class="sig-name descname"><span class="pre">config1</span></span><a class="headerlink" href="https://docs.project.com/configuration.html#confval-config1" title="Permalink to this definition">¶</a></dt>'
+            content = f'<dt class="sig sig-object std" id="confval-config1">\n<span class="sig-name descname"><span class="pre">config1</span></span><a class="headerlink" href="https://docs.project.com/configuration.html#confval-config1" title="{title}">¶</a></dt>'
 
         assert response.json() == {
             "url": "https://docs.project.com/configuration.html#confval-config1",
@@ -154,13 +150,13 @@ def test_dl_identifier_doctool_sphinx(self, app, client, requests_mock):
         assert response.status_code == 200
 
         if sphinx.version_info < (3, 0, 0):  # <3.0
-            content = '<dl class="confval">\n<dt id="confval-config1">\n<code class="sig-name descname">config1</code><a class="headerlink" href="https://docs.project.com/configuration.html#confval-config1" title="Permalink to this definition">¶</a></dt>\n<dd><p>Description: This the description for config1</p>\n<p>Default: <code class="docutils literal notranslate"><span class="pre">\'Default</span> <span class="pre">value</span> <span class="pre">for</span> <span class="pre">config\'</span></code></p>\n<p>Type: bool</p>\n</dd></dl>'
+            content = f'<dl class="confval">\n<dt id="confval-config1">\n<code class="sig-name descname">config1</code><a class="headerlink" href="https://docs.project.com/configuration.html#confval-config1" title="{title}">¶</a></dt>\n<dd><p>Description: This the description for config1</p>\n<p>Default: <code class="docutils literal notranslate"><span class="pre">\'Default</span> <span class="pre">value</span> <span class="pre">for</span> <span class="pre">config\'</span></code></p>\n<p>Type: bool</p>\n</dd></dl>'
         elif sphinx.version_info[:2] == (3, 5):
-            content = '<dl class="std confval">\n<dt id="confval-config1">\n<code class="sig-name descname"><span class="pre">config1</span></code><a class="headerlink" href="https://docs.project.com/configuration.html#confval-config1" title="Permalink to this definition">¶</a></dt>\n<dd><p>Description: This the description for config1</p>\n<p>Default: <code class="docutils literal notranslate"><span class="pre">\'Default</span> <span class="pre">value</span> <span class="pre">for</span> <span class="pre">config\'</span></code></p>\n<p>Type: bool</p>\n</dd></dl>'
+            content = f'<dl class="std confval">\n<dt id="confval-config1">\n<code class="sig-name descname"><span class="pre">config1</span></code><a class="headerlink" href="https://docs.project.com/configuration.html#confval-config1" title="{title}">¶</a></dt>\n<dd><p>Description: This the description for config1</p>\n<p>Default: <code class="docutils literal notranslate"><span class="pre">\'Default</span> <span class="pre">value</span> <span class="pre">for</span> <span class="pre">config\'</span></code></p>\n<p>Type: bool</p>\n</dd></dl>'
         elif sphinx.version_info < (4, 0, 0):  # >3.0,=!3.5.x,<4.0
-            content = '<dl class="std confval">\n<dt id="confval-config1">\n<code class="sig-name descname">config1</code><a class="headerlink" href="https://docs.project.com/configuration.html#confval-config1" title="Permalink to this definition">¶</a></dt>\n<dd><p>Description: This the description for config1</p>\n<p>Default: <code class="docutils literal notranslate"><span class="pre">\'Default</span> <span class="pre">value</span> <span class="pre">for</span> <span class="pre">config\'</span></code></p>\n<p>Type: bool</p>\n</dd></dl>'
+            content = f'<dl class="std confval">\n<dt id="confval-config1">\n<code class="sig-name descname">config1</code><a class="headerlink" href="https://docs.project.com/configuration.html#confval-config1" title="{title}">¶</a></dt>\n<dd><p>Description: This the description for config1</p>\n<p>Default: <code class="docutils literal notranslate"><span class="pre">\'Default</span> <span class="pre">value</span> <span class="pre">for</span> <span class="pre">config\'</span></code></p>\n<p>Type: bool</p>\n</dd></dl>'
         else:  # >=4.0
-            content = '<dl class="std confval">\n<dt class="sig sig-object std" id="confval-config1">\n<span class="sig-name descname"><span class="pre">config1</span></span><a class="headerlink" href="https://docs.project.com/configuration.html#confval-config1" title="Permalink to this definition">¶</a></dt>\n<dd><p>Description: This the description for config1</p>\n<p>Default: <code class="docutils literal notranslate"><span class="pre">\'Default</span> <span class="pre">value</span> <span class="pre">for</span> <span class="pre">config\'</span></code></p>\n<p>Type: bool</p>\n</dd></dl>'
+            content = f'<dl class="std confval">\n<dt class="sig sig-object std" id="confval-config1">\n<span class="sig-name descname"><span class="pre">config1</span></span><a class="headerlink" href="https://docs.project.com/configuration.html#confval-config1" title="{title}">¶</a></dt>\n<dd><p>Description: This the description for config1</p>\n<p>Default: <code class="docutils literal notranslate"><span class="pre">\'Default</span> <span class="pre">value</span> <span class="pre">for</span> <span class="pre">config\'</span></code></p>\n<p>Type: bool</p>\n</dd></dl>'
 
         assert response.json() == {
             "url": "https://docs.project.com/configuration.html#confval-config1",
@@ -232,8 +228,10 @@ def test_glossary_identifier_doctool_sphinx(self, app, client, requests_mock):
         response = client.get(self.api_url, params)
         assert response.status_code == 200
 
+        title = get_anchor_link_title("term")
+
         if sphinx.version_info >= (3, 5, 0):
-            content = f'<dt id="{fragment}">Read the Docs<a class="headerlink" href="https://docs.project.com/glossary.html#{fragment}" title="Permalink to this term">¶</a></dt>'
+            content = f'<dt id="{fragment}">Read the Docs<a class="headerlink" href="https://docs.project.com/glossary.html#{fragment}" title="{title}">¶</a></dt>'
         else:
             content = f'<dt id="{fragment}">Read the Docs</dt>'
 
@@ -258,7 +256,7 @@ def test_glossary_identifier_doctool_sphinx(self, app, client, requests_mock):
             classes = "glossary simple"
 
         if sphinx.version_info >= (3, 5, 0):
-            content = f'<dl class="{classes}">\n\n<dt id="{fragment}">Read the Docs<a class="headerlink" href="https://docs.project.com/glossary.html#{fragment}" title="Permalink to this term">¶</a></dt><dd><p>Best company ever.</p>\n</dd>\n</dl>'
+            content = f'<dl class="{classes}">\n\n<dt id="{fragment}">Read the Docs<a class="headerlink" href="https://docs.project.com/glossary.html#{fragment}" title="{title}">¶</a></dt><dd><p>Best company ever.</p>\n</dd>\n</dl>'
         else:
             content = f'<dl class="{classes}">\n\n<dt id="{fragment}">Read the Docs</dt><dd><p>Best company ever.</p>\n</dd>\n</dl>'
 
@@ -302,11 +300,7 @@ def test_manual_references(self, app, client, requests_mock):
         response = client.get(self.api_url, params)
         assert response.status_code == 200
 
-        # https://github.com/sphinx-doc/sphinx/commit/bc635627d32b52e8e1381f23cddecf26429db1ae
-        if sphinx.version_info < (5, 0, 0):
-            title = "Permalink to this headline"
-        else:
-            title = "Permalink to this heading"
+        title = get_anchor_link_title("heading")
 
         # Note the difference between `<section>` and `<div class="section">`
         if Version(docutils.__version__) >= Version("0.17"):
diff --git a/readthedocs/embed/v3/tests/test_internal_pages.py b/readthedocs/embed/v3/tests/test_internal_pages.py
@@ -4,7 +4,6 @@
 import django_dynamic_fixture as fixture
 import docutils
 import pytest
-import sphinx
 from django.core.cache import cache
 from django.urls import reverse
 from packaging.version import Version
@@ -13,28 +12,24 @@
 from readthedocs.subscriptions.constants import TYPE_EMBED_API
 from readthedocs.subscriptions.products import RTDProductFeature
 
-from .utils import srcdir
+from .utils import get_anchor_link_title, srcdir
 
 
 @pytest.mark.django_db
 @pytest.mark.embed_api
 class TestEmbedAPIv3InternalPages:
-
     @pytest.fixture(autouse=True)
     def setup_method(self, settings):
         settings.USE_SUBDOMAIN = True
-        settings.PUBLIC_DOMAIN = 'readthedocs.io'
+        settings.PUBLIC_DOMAIN = "readthedocs.io"
         settings.RTD_EMBED_API_EXTERNAL_DOMAINS = []
         settings.RTD_DEFAULT_FEATURES = dict(
             [RTDProductFeature(TYPE_EMBED_API).to_item()]
         )
 
-        self.api_url = reverse('embed_api_v3')
+        self.api_url = reverse("embed_api_v3")
 
-        self.project = fixture.get(
-            Project,
-            slug='project'
-        )
+        self.project = fixture.get(Project, slug="project")
 
         yield
         cache.clear()
@@ -45,43 +40,40 @@ def f(*args, **kwargs):
             read_mock = mock.MagicMock()
             read_mock.read.return_value = content
             yield read_mock
+
         return f
 
     @pytest.mark.sphinx("html", srcdir=srcdir, freshenv=True)
     @mock.patch("readthedocs.embed.v3.views.build_media_storage.open")
     @mock.patch("readthedocs.embed.v3.views.build_media_storage.exists")
     def test_default_main_section(self, storage_exists, storage_open, app, client):
         app.build()
-        path = app.outdir / 'index.html'
+        path = app.outdir / "index.html"
         assert path.exists() is True
         content = open(path).read()
 
         storage_exists.return_value = True
         storage_open.side_effect = self._mock_open(content)
 
         params = {
-            'url': 'https://project.readthedocs.io/en/latest/',
+            "url": "https://project.readthedocs.io/en/latest/",
         }
         response = client.get(self.api_url, params)
         assert response.status_code == 200
 
-        # https://github.com/sphinx-doc/sphinx/commit/bc635627d32b52e8e1381f23cddecf26429db1ae
-        if sphinx.version_info < (5, 0, 0):
-            title = "Permalink to this headline"
-        else:
-            title = "Permalink to this heading"
+        title = get_anchor_link_title("heading")
 
         # Note the difference between `<section>` and `<div class="section">`
-        if Version(docutils.__version__) >= Version('0.17'):
+        if Version(docutils.__version__) >= Version("0.17"):
             content = f'<div class="body" role="main">\n            \n  <section id="title">\n<h1>Title<a class="headerlink" href="https://project.readthedocs.io/en/latest/#title" title="{title}">¶</a></h1>\n<p>This is an example page used to test EmbedAPI parsing features.</p>\n<section id="sub-title">\n<h2>Sub-title<a class="headerlink" href="https://project.readthedocs.io/en/latest/#sub-title" title="{title}">¶</a></h2>\n<p>This is a reference to <a class="reference internal" href="https://project.readthedocs.io/en/latest/#sub-title"><span class="std std-ref">Sub-title</span></a>.</p>\n</section>\n<section id="manual-reference-section">\n<span id="manual-reference"></span><h2>Manual Reference Section<a class="headerlink" href="https://project.readthedocs.io/en/latest/#manual-reference-section" title="{title}">¶</a></h2>\n<p>This is a reference to a manual reference <a class="reference internal" href="https://project.readthedocs.io/en/latest/#manual-reference"><span class="std std-ref">Manual Reference Section</span></a>.</p>\n</section>\n</section>\n\n\n          </div>'
         else:
             content = f'<div class="body" role="main">\n            \n  <div class="section" id="title">\n<h1>Title<a class="headerlink" href="https://project.readthedocs.io/en/latest/#title" title="{title}">¶</a></h1>\n<p>This is an example page used to test EmbedAPI parsing features.</p>\n<div class="section" id="sub-title">\n<h2>Sub-title<a class="headerlink" href="https://project.readthedocs.io/en/latest/#sub-title" title="{title}">¶</a></h2>\n<p>This is a reference to <a class="reference internal" href="https://project.readthedocs.io/en/latest/#sub-title"><span class="std std-ref">Sub-title</span></a>.</p>\n</div>\n<div class="section" id="manual-reference-section">\n<span id="manual-reference"></span><h2>Manual Reference Section<a class="headerlink" href="https://project.readthedocs.io/en/latest/#manual-reference-section" title="{title}">¶</a></h2>\n<p>This is a reference to a manual reference <a class="reference internal" href="https://project.readthedocs.io/en/latest/#manual-reference"><span class="std std-ref">Manual Reference Section</span></a>.</p>\n</div>\n</div>\n\n\n          </div>'
 
         assert response.json() == {
-            'url': 'https://project.readthedocs.io/en/latest/',
-            'fragment': None,
-            'content': content,
-            'external': False,
+            "url": "https://project.readthedocs.io/en/latest/",
+            "fragment": None,
+            "content": content,
+            "external": False,
         }
 
     @pytest.mark.sphinx("html", srcdir=srcdir, freshenv=False)
diff --git a/readthedocs/embed/v3/tests/utils.py b/readthedocs/embed/v3/tests/utils.py
@@ -1,8 +1,23 @@
 import os
 
+import sphinx
 
 srcdir = os.path.join(
     os.path.dirname(os.path.abspath(__file__)),
     "examples",
     "default",
 )
+
+
+def get_anchor_link_title(thing):
+    # https://github.com/sphinx-doc/sphinx/commit/bc635627d32b52e8e1381f23cddecf26429db1ae
+    if sphinx.version_info < (5, 0, 0):
+        if thing == "heading":
+            thing = "headline"
+        title = f"Permalink to this {thing}"
+    # https://github.com/sphinx-doc/sphinx/commit/7e9a2066c2f31eda53d075f5a8b20a7430ca0c61
+    elif sphinx.version_info >= (7, 2, 0):
+        title = f"Link to this {thing}"
+    else:
+        title = f"Permalink to this {thing}"
+    return title
diff --git a/tox.embedapi.ini b/tox.embedapi.ini
