DOP-2611: Improve handling of null characters in docutils output

Author: i80and

snooty/rstparser.py

@@ -31,7 +31,6 @@
 import docutils.parsers.rst.states
 import docutils.statemachine
 import docutils.utils
-from docutils.nodes import unescape
 from typing_extensions import Protocol
 
 from . import n, specparser, util
@@ -89,12 +88,22 @@ def split(self, text: str) -> List[str]:
 docutils.nodes.dupname = lambda node, name: None
 
 
+def unescape_backslashes(text: str) -> str:
+    """docutils replaces backslashes with null characters. Deal with this in
+    a fairly inane way that matches how backslashes seem to be used in our
+    corpus."""
+    return text.replace("\x00<", "<").replace("\x00>", ">").replace("\x00", "\\")
+
+
 def parse_explicit_title(text: str) -> Tuple[str, Optional[str]]:
     match = PAT_EXPLICIT_TITLE.match(text)
+
     if match:
-        return unescape(match["target"]), unescape(match["label"])
+        return unescape_backslashes(match["target"]), unescape_backslashes(
+            match["label"]
+        )
 
-    return (unescape(text), None)
+    return (unescape_backslashes(text), None)
 
 
 def strip_parameters(target: str) -> str:

snooty/test_postprocess.py

@@ -302,10 +302,10 @@ def test_guides() -> None:
       :description: The description exists! No errors
 
       .. guide:: /path/to/guide2.txt
-   
+
    .. chapter:: No Guides
       :description: No guides
-    
+
    .. guide:: /path/to/guide3.txt
 
    .. chapter::
@@ -357,12 +357,12 @@ def test_guides() -> None:
                 "source/index.txt"
             ): """
 .. chapters::
-   
+
    .. chapter:: Test
       :description: This is a chapter
 
       .. guide:: /path/to/guide1.txt
-  
+
    .. chapter:: Test
       :description: This is a chapter
 
@@ -386,7 +386,7 @@ def test_guides() -> None:
       :description: This is a chapter
 
       .. guide:: /path/to/guide1.txt
-   
+
    .. chapter:: Test: The Sequel
       :description: This is another chapter
 
@@ -2207,3 +2207,41 @@ def test_block_substitutions_in_lists() -> None:
     </directive>
 </root>""",
         )
+
+
+def test_targets_with_backslashes() -> None:
+    with make_test(
+        {
+            Path(
+                "source/index.txt"
+            ): r"""
+:phpmethod:`MongoDB\Database::listCollections()`
+:phpmethod:`foobar <MongoDB\Database::listCollections()>`
+
+.. phpmethod:: MongoDB\Database::listCollections()
+"""
+        }
+    ) as result:
+        assert not result.diagnostics[FileId("index.txt")]
+        check_ast_testing_string(
+            result.pages[FileId("index.txt")].ast,
+            r"""
+<root fileid="index.txt">
+    <paragraph>
+        <ref_role domain="mongodb" name="phpmethod" target="phpmethod.MongoDB\Database::listCollections()" fileid="['index', 'mongodb-phpmethod-phpmethod.MongoDB-Database--listCollections--']">
+            <literal><text>MongoDB\Database::listCollections()</text></literal>
+        </ref_role>
+        <text> </text>
+        <ref_role domain="mongodb" name="phpmethod" target="phpmethod.MongoDB\Database::listCollections()" fileid="['index', 'mongodb-phpmethod-phpmethod.MongoDB-Database--listCollections--']">
+            <literal><text>foobar</text></literal>
+        </ref_role>
+    </paragraph>
+    <target domain="mongodb" name="phpmethod" html_id="mongodb-phpmethod-phpmethod.MongoDB-Database--listCollections--">
+        <directive_argument><literal><text>MongoDB\Database::listCollections()</text></literal></directive_argument>
+        <target_identifier ids="['phpmethod.MongoDB\\Database::listCollections()']">
+            <text>MongoDB\Database::listCollections()</text>
+        </target_identifier>
+    </target>
+</root>
+""",
+        )

stubs/docutils/nodes.pyi

@@ -4,9 +4,6 @@ from typing import Any, Optional, List, Iterable, Union
 from typing_extensions import Protocol
 
 
-def unescape(text: str) -> str: ...
-
-
 def make_id(input_value: str) -> str: ...