Fix viewcode test

Previously the viewcode test was doing string comparisons for HTML tags,
this was not very robust and resulted in failures once the sphinx
generated html added more attributes.  The tests now utilize beautiful
soup to find the tags and compares the text of the tags.

Author: speedyleion

src/sphinx_c_autodoc/__init__.py

@@ -286,9 +286,7 @@ def get_compilation_database(self) -> Optional[str]:
 
         return None
 
-    def get_doc(
-        self, encoding: Optional[str] = None, ignore: int = None
-    ) -> List[List[str]]:
+    def get_doc(self, ignore: int = None) -> Optional[List[List[str]]]:
         """Decode and return lines of the docstring(s) for the object."""
         docstring = self.object.get_doc()
         tab_width = self.directive.state.document.settings.tab_width

src/sphinx_c_autodoc/viewcode/__init__.py

@@ -98,6 +98,7 @@ def missing_reference(
     """
     # pylint: disable=unused-argument
     if node["reftype"] == f"{C_DOMAIN_LINK_PREFIX}viewcode":
+        assert app.builder is not None
         # We have to wait until here to see if the module actually exists as a
         # plain c directive could be reference a module before the auto c
         # directives are encountered.
@@ -135,6 +136,7 @@ def add_source_listings(app: Sphinx) -> Iterator[Tuple[str, Dict[str, Any], str]
         of the page, the name of the template to use for generating the final
         page.
     """
+    assert app.builder is not None
     modules_to_list = getattr(app.builder.env, "_viewcode_c_modules", {})
 
     iterator = status_iterator(
@@ -189,6 +191,7 @@ def _insert_documentation_backlinks(
         code_listing (ViewCodeListing):
             Contains the documentation locations which documented `highlighted_code`.
     """
+    assert app.builder is not None
     for doc in code_listing.doc_links.values():
         construct = _find_construct(doc.fullname, code_listing.ast)
 
@@ -411,6 +414,9 @@ def _add_pending_source_cross_reference(
     if module is None:
         return
 
+    assert app.builder is not None
+    assert app.builder.env is not None
+
     source_page = _get_source_page_name(module)
 
     # Using the `viewcode-link` to be consistent with the python versions in
@@ -453,6 +459,9 @@ def _add_pending_back_reference(app: Sphinx, signode: Node, fullname: str) -> No
     if module is None:
         return
 
+    assert app.builder is not None
+    assert app.builder.env is not None
+
     env = app.builder.env
     code_listing = env._viewcode_c_modules.get(module)  # type: ignore
     if code_listing is None:

tests/viewcode/test_viewcode.py

@@ -10,6 +10,7 @@
 import re
 import os
 from sphinx.cmd.build import main
+from bs4 import BeautifulSoup
 
 
 SCRIPT_DIR = os.path.dirname(__file__)
@@ -41,51 +42,61 @@ def test_viewcode_of_sphinx_project(tmp_path):
     with file_name.open() as f:
         contents = f.read()
 
+    # Looking for tags of the form
+    #
+    #   <a class="reference internal" href="_modules/example.c.html#c.MY_COOL_MACRO"><span class="viewcode-link"><span class="pre">[source]</span></span></a>
     chosen_links = (
-        '<dt id="c.MY_COOL_MACRO">',
-        '<a class="reference internal" href="_modules/example.c.html#c.MY_COOL_MACRO"><span class="viewcode-link">[source]</span></a>',
-        '<dt id="c.members_documented_with_napoleon.two.nested_two">',
-        '<a class="reference internal" href="_modules/example.c.html#c.members_documented_with_napoleon.two.nested_two"><span class="viewcode-link">[source]</span></a>',
+        "_modules/example.c.html#c.MY_COOL_MACRO",
+        "_modules/example.c.html#c.members_documented_with_napoleon.two.nested_two",
     )
-    for l in chosen_links:
-        assert l in contents
+
+    soup = BeautifulSoup(contents)
+    for href in chosen_links:
+        tag = soup.find("a", {"href": href})
+        assert "[source]" == tag.text
 
     file_name = tmp_path / "sub_dir" / "file_2.html"
     with file_name.open() as f:
         contents = f.read()
 
     chosen_links = (
-        '<a class="reference internal" href="../_modules/file_2.c.html#c.unknown_member.foo"><span class="viewcode-link">[source]</span></a>',
-        '<a class="reference internal" href="../_modules/file_2.c.html#c.file_level_variable"><span class="viewcode-link">[source]</span></a>',
+        "../_modules/file_2.c.html#c.unknown_member.foo",
+        "../_modules/file_2.c.html#c.file_level_variable",
     )
-    for l in chosen_links:
-        assert l in contents
+    soup = BeautifulSoup(contents)
+    for href in chosen_links:
+        tag = soup.find("a", {"href": href})
+        assert "[source]" == tag.text
 
     # Test the back links
     file_name = tmp_path / "_modules" / "example.c.html"
     with file_name.open() as f:
         contents = f.read()
 
     chosen_links = (
-        '<div class="viewcode-block" id="c.members_documented_with_napoleon.two.nested_two"><a class="viewcode-back" href="../example.html#c.members_documented_with_napoleon.two.nested_two">[docs]</a>',
-        '<div class="viewcode-block" id="c.MY_COOL_MACRO"><a class="viewcode-back" href="../example.html#c.MY_COOL_MACRO">[docs]</a>',
+        "../example.html#c.members_documented_with_napoleon.two.nested_two",
+        "../example.html#c.MY_COOL_MACRO",
     )
-    for l in chosen_links:
-        assert l in contents
+    soup = BeautifulSoup(contents)
+    for href in chosen_links:
+        tag = soup.find("a", {"href": href})
+        assert "[docs]" == tag.text
 
     # Test normal C constructs elsewhere in docs
     file_name = tmp_path / "viewcode.html"
     with file_name.open() as f:
         contents = f.read()
 
     chosen_links = (
-        '<a class="reference internal" href="_modules/example.c.html#c.napoleon_documented_function"><span class="viewcode-link">[source]</span></a>',
+        "_modules/example.c.html#c.napoleon_documented_function",
         # One needs to use noindex in order to avoid sphinx warning and once
         # one uses noindex then the permalinks are no longer generated :(
-        # '<a class="headerlink" href="#c.napoleon_documented_function" title="Permalink to this definition">',
+        # "#c.napoleon_documented_function"
     )
-    for l in chosen_links:
-        assert l in contents
+    soup = BeautifulSoup(contents)
+    for href in chosen_links:
+        tag = soup.find("a", {"href": href})
+        assert "[source]" == tag.text
 
     # Ensure only the one function that actually had a source file to be able to link to creates a link
     link_count = len(re.findall("viewcode-link", contents))

tox.ini

@@ -33,6 +33,7 @@ deps =
     # Lock clang back to a specific version for reliable github action builds
     clang==6.0
     sphinxcontrib.autoprogram
+    types-docutils
 commands =
     pylint: pylint {toxinidir}/src/sphinx_c_autodoc -r n
     pycodestyle: pycodestyle {toxinidir}/src/sphinx_c_autodoc