👌 IMPROVE: Changed document identification (#51)

Move the comparison of sitemaps and
identification of changed documents to `SiteMap.get_changed`,
and add tests for this method.

Author: chrisjsewell

sphinx_external_toc/api.py

@@ -155,3 +155,21 @@ def as_json(self) -> Dict[str, Any]:
         if self.file_format:
             data["file_format"] = self.file_format
         return data
+
+    def get_changed(self, previous: "SiteMap") -> Set[str]:
+        """Compare this sitemap to another and return a list of changed documents.
+
+        Note: for sphinx, file extensions should be removed to get docnames
+        """
+        changed_docs = set()
+        # check if the root document has changed
+        if self.root.docname != previous.root.docname:
+            changed_docs.add(self.root.docname)
+        for name, doc in self._docs.items():
+            if name not in previous:
+                changed_docs.add(name)
+                continue
+            prev_doc = previous[name]
+            if prev_doc != doc:
+                changed_docs.add(name)
+        return changed_docs

sphinx_external_toc/events.py

@@ -133,15 +133,10 @@ def add_changed_toctrees(
     # move external_site_map from config to env
     app.env.external_site_map = site_map = app.config.external_site_map
     # Compare to previous map, to record docnames with new or changed toctrees
-    changed_docs = set()
-    if previous_map:
-        for docname in site_map:
-            if (
-                docname not in previous_map
-                or site_map[docname] != previous_map[docname]
-            ):
-                changed_docs.add(docname)
-    return changed_docs
+    if not previous_map:
+        return set()
+    filenames = site_map.get_changed(previous_map)
+    return {remove_suffix(name, app.config.source_suffix) for name in filenames}
 
 
 class TableOfContentsNode(nodes.Element):

tests/test_api.py

@@ -0,0 +1,56 @@
+from sphinx_external_toc.api import Document, FileItem, SiteMap, TocTree
+
+
+def test_sitemap_get_changed_identical():
+    """Test for identical sitemaps."""
+    root1 = Document("root")
+    root1.subtrees = [TocTree([])]
+    sitemap1 = SiteMap(root1)
+    root2 = Document("root")
+    root2.subtrees = [TocTree([])]
+    sitemap2 = SiteMap(root2)
+    assert sitemap1.get_changed(sitemap2) == set()
+
+
+def test_sitemap_get_changed_root():
+    """Test for sitemaps with changed root."""
+    doc1 = Document("doc1")
+    doc2 = Document("doc2")
+    sitemap1 = SiteMap(doc1)
+    sitemap1["doc2"] = doc2
+    sitemap2 = SiteMap(doc2)
+    sitemap1["doc1"] = doc1
+    assert sitemap1.get_changed(sitemap2) == {"doc1"}
+
+
+def test_sitemap_get_changed_title():
+    """Test for sitemaps with changed title."""
+    root1 = Document("root")
+    root1.title = "a"
+    sitemap1 = SiteMap(root1)
+    root2 = Document("root")
+    root2.title = "b"
+    sitemap2 = SiteMap(root2)
+    assert sitemap1.get_changed(sitemap2) == {"root"}
+
+
+def test_sitemap_get_changed_subtrees():
+    """Test for sitemaps with changed subtrees."""
+    root1 = Document("root")
+    root1.subtrees = [TocTree([])]
+    sitemap1 = SiteMap(root1)
+    root2 = Document("root")
+    root2.subtrees = [TocTree([FileItem("a")])]
+    sitemap2 = SiteMap(root2)
+    assert sitemap1.get_changed(sitemap2) == {"root"}
+
+
+def test_sitemap_get_changed_subtrees_numbered():
+    """Test for sitemaps with changed numbered option."""
+    root1 = Document("root")
+    root1.subtrees = [TocTree([], numbered=False)]
+    sitemap1 = SiteMap(root1)
+    root2 = Document("root")
+    root2.subtrees = [TocTree([], numbered=True)]
+    sitemap2 = SiteMap(root2)
+    assert sitemap1.get_changed(sitemap2) == {"root"}