fix: Load Sphinx inventories whose dispname spans multiple lines

Yoshanuikabundi · pawamoy · commit aa6ac717e819 · 2025-03-31T10:04:42.000+02:00
When a display name spans multiple lines, both mkdocstrings and Sphinx simply print the newline character and then the continuation. This is because a display name spanning multiple lines is a rare edge case that was not accounted for in either software. However, while Sphinx discards any inventory lines that do not parse (such as the continuation line), mkdocstrings raises an error, causing the entire inventory file to fail to load. This continuation line behavior can be seen in the wild in the OpenEye toolkits inventory file and a few Open Force Field inventory files. These projects' inventories cannot be used with mkdocstrings because of the raised error. Note that in Sphinx, these inventory files are read succesfully, but the continuation lines are discarded, truncating the display name. In theory, a continuation line that by chance did parse correctly would be interpreted by both packages as a new inventory item. This commit appends the continuation line to the previous inventory item display name when it fails to parse. This allows these inventory files to be loaded while preserving the original display name. Note that the theoretical continuation line that parses by chance is not addressed. Round-trip tests and additional Sphinx tests are added to check the new behavior. OpenEye Toolkits inventory file: https://docs.eyesopen.com/toolkits/python/objects.inv Open Force Field Toolkit inventory file: https://docs.openforcefield.org/projects/toolkit/en/stable/objects.inv BespokeFit inventory file: https://docs.openforcefield.org/projects/bespokefit/en/stable/objects.inv
diff --git a/src/mkdocstrings/_internal/inventory.py b/src/mkdocstrings/_internal/inventory.py
@@ -8,7 +8,7 @@
 import re
 import zlib
 from textwrap import dedent
-from typing import TYPE_CHECKING, BinaryIO
+from typing import TYPE_CHECKING, BinaryIO, Literal, overload
 
 if TYPE_CHECKING:
     from collections.abc import Collection
@@ -66,11 +66,21 @@ def format_sphinx(self) -> str:
     sphinx_item_regex = re.compile(r"^(.+?)\s+(\S+):(\S+)\s+(-?\d+)\s+(\S+)\s*(.*)$")
     """Regex to parse a Sphinx v2 inventory line."""
 
+    @overload
     @classmethod
-    def parse_sphinx(cls, line: str) -> InventoryItem:
+    def parse_sphinx(cls, line: str, *, return_none: Literal[False]) -> InventoryItem: ...
+
+    @overload
+    @classmethod
+    def parse_sphinx(cls, line: str, *, return_none: Literal[True]) -> InventoryItem | None: ...
+
+    @classmethod
+    def parse_sphinx(cls, line: str, *, return_none: bool = False) -> InventoryItem | None:
         """Parse a line from a Sphinx v2 inventory file and return an `InventoryItem` from it."""
         match = cls.sphinx_item_regex.search(line)
         if not match:
+            if return_none:
+                return None
             raise ValueError(line)
         name, domain, role, priority, uri, dispname = match.groups()
         if uri.endswith("$"):
@@ -167,7 +177,12 @@ def parse_sphinx(cls, in_file: BinaryIO, *, domain_filter: Collection[str] = ())
         for _ in range(4):
             in_file.readline()
         lines = zlib.decompress(in_file.read()).splitlines()
-        items = [InventoryItem.parse_sphinx(line.decode("utf8")) for line in lines]
+        items: list[InventoryItem] = list(
+            filter(
+                bool,  # type: ignore[arg-type]
+                (InventoryItem.parse_sphinx(line.decode("utf8"), return_none=True) for line in lines),
+            ),
+        )
         if domain_filter:
             items = [item for item in items if item.domain in domain_filter]
         return cls(items)
diff --git a/tests/test_inventory.py b/tests/test_inventory.py
@@ -11,8 +11,6 @@
 
 from mkdocstrings import Inventory, InventoryItem
 
-sphinx = pytest.importorskip("sphinx.util.inventory", reason="Sphinx is not installed")
-
 
 @pytest.mark.parametrize(
     "our_inv",
@@ -21,10 +19,13 @@
         Inventory([InventoryItem(name="object_path", domain="py", role="obj", uri="page_url")]),
         Inventory([InventoryItem(name="object_path", domain="py", role="obj", uri="page_url#object_path")]),
         Inventory([InventoryItem(name="object_path", domain="py", role="obj", uri="page_url#other_anchor")]),
+        Inventory([InventoryItem(name="o", domain="py", role="obj", uri="u#o", dispname="first line\nsecond line")]),
     ],
 )
 def test_sphinx_load_inventory_file(our_inv: Inventory) -> None:
     """Perform the 'live' inventory load test."""
+    sphinx = pytest.importorskip("sphinx.util.inventory", reason="Sphinx is not installed")
+
     buffer = BytesIO(our_inv.format_sphinx())
     sphinx_inv = sphinx.InventoryFile.load(buffer, "", join)
 
@@ -37,6 +38,8 @@ def test_sphinx_load_inventory_file(our_inv: Inventory) -> None:
 
 def test_sphinx_load_mkdocstrings_inventory_file() -> None:
     """Perform the 'live' inventory load test on mkdocstrings own inventory."""
+    sphinx = pytest.importorskip("sphinx.util.inventory", reason="Sphinx is not installed")
+
     mkdocs_config = load_config()
     mkdocs_config["plugins"].run_event("startup", command="build", dirty=False)
     try:
@@ -53,3 +56,29 @@ def test_sphinx_load_mkdocstrings_inventory_file() -> None:
 
     for item in own_inv.values():
         assert item.name in sphinx_inv[f"{item.domain}:{item.role}"]
+
+
+@pytest.mark.parametrize(
+    "our_inv",
+    [
+        Inventory(),
+        Inventory([InventoryItem(name="object_path", domain="py", role="obj", uri="page_url")]),
+        Inventory([InventoryItem(name="object_path", domain="py", role="obj", uri="page_url#object_path")]),
+        Inventory([InventoryItem(name="object_path", domain="py", role="obj", uri="page_url#other_anchor")]),
+        Inventory([InventoryItem(name="o", domain="py", role="obj", uri="u#o", dispname="first line\nsecond line")]),
+    ],
+)
+def test_mkdocstrings_roundtrip_inventory_file(our_inv: Inventory) -> None:
+    """Save some inventory files, then load them in again."""
+    buffer = BytesIO(our_inv.format_sphinx())
+    round_tripped = Inventory.parse_sphinx(buffer)
+
+    assert our_inv.keys() == round_tripped.keys()
+    for key, value in our_inv.items():
+        round_tripped_item = round_tripped[key]
+        assert round_tripped_item.name == value.name
+        assert round_tripped_item.domain == value.domain
+        assert round_tripped_item.role == value.role
+        assert round_tripped_item.uri == value.uri
+        assert round_tripped_item.priority == value.priority
+        assert round_tripped_item.dispname == value.dispname.splitlines()[0]
