Normalize links in docs validator for nested sections (#8541)

* normalize links for nested sections

* add test cases for links functionality

* update test links

* use different links

datadog_checks_dev/datadog_checks/dev/tooling/specs/docs/core.py

@@ -3,6 +3,7 @@
 # Licensed under a 3-clause BSD style license (see LICENSE)
 
 import re
+from collections import deque
 
 import markdown
 from markdown.blockprocessors import ReferenceProcessor
@@ -39,8 +40,16 @@ def normalize_links(self):
         # Markdown doc reference: https://www.markdownguide.org/basic-syntax/#links
 
         for fidx, file in enumerate(self.data['files'], 1):
-            for sidx, section in enumerate(file['sections'], 1):
+            sections = deque(enumerate(file['sections'], 1))
+            while sections:
+                sidx, section = sections.popleft()
                 section['description'] = self._normalize(section['description'], fidx, sidx)
+                if 'sections' in section:
+                    nested_sections = [
+                        (f'{sidx}.{subidx}', subsection) for subidx, subsection in enumerate(section['sections'], 1)
+                    ]
+                    # extend left backwards for correct order of sections
+                    sections.extendleft(nested_sections[::-1])
 
     def _normalize(self, text, fidx, sidx):
         # use the markdown internal processor class to extract all references into a dict

datadog_checks_dev/tests/tooling/docs/test_load.py

@@ -546,3 +546,56 @@ def test_bar_valid(_):
     doc.load()
 
     assert not doc.errors
+
+
+@mock.patch('datadog_checks.dev.tooling.specs.docs.spec.load_manifest', return_value=MOCK_RESPONSE)
+def test_sections_link(_):
+
+    doc = get_doc(
+        """
+        name: foo
+        files:
+        - name: README.md
+          sections:
+          - name: foo
+            header_level: 1
+            description: |
+                [link][1]
+
+                [1]: datadoghq.com
+        """
+    )
+    doc.load()
+    expected_description = '[link](datadoghq.com)'
+    assert doc.data['files'][0]['sections'][0]['description'] == expected_description
+
+
+@mock.patch('datadog_checks.dev.tooling.specs.docs.spec.load_manifest', return_value=MOCK_RESPONSE)
+def test_nested_sections_link(_):
+
+    doc = get_doc(
+        """
+        name: foo
+        files:
+        - name: README.md
+          sections:
+          - name: foo
+            header_level: 1
+            description: |
+                [link][1]
+
+                [1]: datadoghq.com
+            sections:
+            - name: bar
+              header_level: 1
+              description: |
+                [foo][1]
+
+                [1]: foo.bar
+        """
+    )
+    doc.load()
+    expected_description = '[link](datadoghq.com)'
+    expected_nested_description = '[foo](foo.bar)'
+    assert doc.data['files'][0]['sections'][0]['description'] == expected_description
+    assert doc.data['files'][0]['sections'][0]['sections'][0]['description'] == expected_nested_description