DOCSP-5634: attach an id to headings

Author: i80and

snooty/gizaparser/nodes.py

@@ -1,6 +1,7 @@
 import dataclasses
 import logging
 import re
+import docutils.nodes
 import networkx
 from dataclasses import dataclass, field
 from pathlib import Path, PurePath
@@ -9,6 +10,7 @@
                    Match
 from ..flutter import checked
 from ..types import Diagnostic, Page, EmbeddedRstParser, SerializableType, ProjectConfig
+from .. import util
 
 _T = TypeVar('_T', str, object)
 PAT_SUBSTITUTION = re.compile(r'\{\{([\w-]+)\}\}')
@@ -262,8 +264,17 @@ def render_heading(self, parse_rst: EmbeddedRstParser) -> Sequence[SerializableT
             heading_text = 'Optional: ' + heading_text
 
         result = parse_rst(heading_text, self.line, True)
+
+        # Generate an anchor ID for this heading. It would be useful for this
+        # to be unique, but it's not possible to do so in a repeatable fashion
+        # without seeing the whole page, so doing that has to fall to the
+        # renderer.
+        heading_id = docutils.nodes.make_id(
+            ''.join(util.ast_get_text(node) for node in result))
+
         return ({
             'type': 'heading',
             'position': {'start': {'line': self.line}},
-            'children': result
+            'children': result,
+            'id': heading_id
         },)

snooty/gizaparser/test_steps.py

@@ -42,34 +42,43 @@ def create_page() -> Tuple[Page, EmbeddedRstParser]:
     assert len(pages) == 1
     print(repr(ast_to_testing_string(pages[0].ast)))
     assert ast_to_testing_string(pages[0].ast) == ''.join((
-        '<directive name="steps"><directive name="step"><section><heading><text>Import the public ',
-        'key used by the package management system.</text></heading><paragraph><text>Issue the ',
+        '<directive name="steps"><directive name="step">',
+        '<section>',
+        '<heading id="import-the-public-key-used-by-the-package-management-system">',
+        '<text>Import the public key used by the package management system.</text>',
+        '</heading><paragraph><text>Issue the ',
         'following command to import the\n</text><reference ',
         'refuri="https://www.mongodb.org/static/pgp/server-3.4.asc">',
         '<text>MongoDB public GPG Key</text>',
         '</reference><target ids="[\'mongodb-public-gpg-key\']" ',
         'refuri="https://www.mongodb.org/static/pgp/server-3.4.asc">',
         '</target></paragraph></section></directive>',
 
-        '<directive name="step"><section><heading><text>Create a </text><literal><text>',
+        '<directive name="step">',
+        '<section>',
+        '<heading id="create-a-etc-apt-sources-list-d-mongodb-org-3-4-list-file-for-mongodb">',
+        '<text>Create a </text><literal><text>',
         '/etc/apt/sources.list.d/mongodb-org-3.4.list</text></literal><text> file for </text>',
         '<role name="guilabel" label="',
         '{\'type\': \'text\', \'value\': \'MongoDB\', \'position\': {\'start\': {\'line\': 1}}}',
         '"></role>',
         '<text>.</text></heading>',
-        '<section><heading><text>Optional: action heading</text></heading>'
+        '<section><heading id="optional-action-heading">',
+        '<text>Optional: action heading</text></heading>'
         '<paragraph><text>Create the list file using the command appropriate for ',
         'your version\nof Debian.</text></paragraph>',
         '<paragraph><text>action-content</text></paragraph>',
         '<paragraph><text>action-post</text></paragraph>',
         '</section></section></directive>',
 
-        '<directive name="step"><section><heading><text>Reload local package database.</text>',
+        '<directive name="step"><section>',
+        '<heading id="reload-local-package-database"><text>Reload local package database.</text>',
         '</heading><paragraph><text>Issue the following command to reload the local package ',
         'database:</text></paragraph><code lang="sh" copyable="True">sudo apt-get update\n</code>',
         '</section></directive>',
 
-        '<directive name="step"><section><heading><text>Install the MongoDB packages.</text>',
+        '<directive name="step"><section><heading id="install-the-mongodb-packages">',
+        '<text>Install the MongoDB packages.</text>',
         '</heading><paragraph><text>hi</text></paragraph>',
         '<paragraph><text>You can install either the latest stable version of MongoDB ',
         'or a\nspecific version of MongoDB.</text></paragraph>',

snooty/parser.py

@@ -230,6 +230,9 @@ def dispatch_visit(self, node: docutils.nodes.Node) -> None:
             doc['type'] = 'listItem'
         elif node_name == 'title':
             doc['type'] = 'heading'
+            # Attach an anchor ID to this section
+            assert node.parent
+            doc['id'] = node.parent['ids'][0]
         elif node_name == 'reference':
             for attr_name in ('refuri', 'refname'):
                 if attr_name in node:

snooty/test_legacy_guides.py

@@ -21,7 +21,7 @@ def test_legacy_guides() -> None:
 
     correct = ''.join((
         '<root guide="">',
-        '<section><heading><text>Sample App</text></heading>',
+        '<section><heading id="sample-app"><text>Sample App</text></heading>',
         '<directive name="author"><text>MongoDB</text></directive>',
         '<directive name="category"><text>Getting Started</text></directive>',
         '<directive name="languages"><list>',

snooty/util.py

@@ -167,3 +167,16 @@ def __exit__(self, *args: object) -> None:
 
     def __len__(self) -> int:
         return sum(len(w) for w in self.directories.values())
+
+
+def ast_get_text(ast: Any) -> str:
+    """Return pure textual content from a given AST node."""
+    if ast.get('type') == 'text':
+        return cast(str, ast['value'])
+
+    label = ast.get('label', None)
+    if label:
+        return ast_get_text(label)
+
+    children = ast.get('children', ())
+    return ''.join(ast_get_text(child) for child in children)

stubs/docutils/nodes.pyi

@@ -4,6 +4,9 @@ from typing import Any, Optional, Sequence, Iterable, Union
 from typing_extensions import Protocol
 
 
+def make_id(input_value: str) -> str: ...
+
+
 class NodeVisitor(Protocol):
     def dispatch_visit(self, node: docutils.nodes.Node) -> None: ...
     def dispatch_departure(self, node: docutils.nodes.Node) -> None: ...