remove hacks annotating data into the synthesized landing page

scripts/build_docs.py

@@ -29,7 +29,7 @@
 from pathlib import Path
 
 from strip_availability import strip_archive
-from curate_navigator import curate_navigator, set_version_paragraph, validate_navigation, NavigationError
+from curate_navigator import curate_navigator, validate_navigation, NavigationError
 
 
 class ArchiveFetchError(Exception):
@@ -148,6 +148,9 @@ def validate_sources(config):
     else:
         if not config["version"].get("slug"):
             errors.append("Top-level 'version' object is missing 'slug'")
+        # 'descriptive-name' is validated and recorded in build-manifest.json but
+        # not otherwise consumed by the build; reserved for a future narrative use
+        # (e.g. re-introducing a landing-page blurb — see hacking-synthesized-landing-page.md).
         if not config["version"].get("descriptive-name"):
             errors.append("Top-level 'version' object is missing 'descriptive-name'")
 
@@ -768,7 +771,7 @@ def inject_custom_templates_into_stubs(archive_path, common_dir):
     return patched
 
 
-def _finalize_combined_archive(all_archives, output_dir, version_slug, docc_cmd, prior_failed, common_dir=None, navigation=None, hosting_base_path=None, version=None):
+def _finalize_combined_archive(all_archives, output_dir, version_slug, docc_cmd, prior_failed, common_dir=None, navigation=None, hosting_base_path=None):
     """Merge per-source archives and apply the static-hosting transform.
 
     Returns (succeeded_steps, failed_steps): names that should be added to
@@ -810,10 +813,6 @@ def _finalize_combined_archive(all_archives, output_dir, version_slug, docc_cmd,
         print("Error: docc merge failed")
         return [], ["combined-merge"]
 
-    descriptive_name = (version or {}).get("descriptive-name")
-    if descriptive_name:
-        set_version_paragraph(combined_output, f"Swift version: {descriptive_name}")
-
     if navigation is not None:
         try:
             curate_navigator(combined_output, navigation)
@@ -1023,7 +1022,7 @@ def attempt_build(index, source, fatal=(), recoverable=()):
         s_steps, f_steps = _finalize_combined_archive(
             all_archives, output_dir, version_slug, tools.docc, failed,
             common_dir=common_dir, navigation=navigation,
-            hosting_base_path=hosting_base_path, version=version,
+            hosting_base_path=hosting_base_path,
         )
         succeeded.extend(s_steps)
         failed.extend(f_steps)

scripts/curate_navigator.py

@@ -295,31 +295,6 @@ def _section_anchor(title):
     return "-".join(title.split())
 
 
-def set_version_paragraph(archive_path, text):
-    """Set the synthesized landing page's body to a single paragraph of text.
-
-    Overwrites any existing `primaryContentSections` in data/documentation.json — the
-    freshly-merged landing page ships with none (DocC omits empty content sections), so
-    replacing the array wholesale keeps repeated builds idempotent. No-op when
-    data/documentation.json is absent. See hacking-synthesized-landing-page.md.
-    """
-    page = Path(archive_path) / "data" / "documentation.json"
-    if not page.is_file():
-        return
-    doc = json.loads(page.read_text())
-    doc["primaryContentSections"] = [{
-        "kind": "content",
-        "content": [{
-            "type": "paragraph",
-            "inlineContent": [{"type": "text", "text": text}],
-        }],
-    }]
-
-    tmp = page.with_suffix(".json.tmp")
-    tmp.write_text(json.dumps(doc, indent=2, ensure_ascii=False) + "\n")
-    os.replace(tmp, page)
-
-
 def dry_run(archive_path, navigation):
     """Compute the curated navigator WITHOUT modifying the archive.
 

scripts/hacking-synthesized-landing-page.md

@@ -1,5 +1,13 @@
 # Hacking the Synthesized Landing Page Body — DocC Merge Post-Processing
 
+> **Status: not currently wired up.** `set_version_paragraph()` and its call
+> from `_finalize_combined_archive()` have been removed from the build
+> scripts — the combined archive's landing page no longer gets a "Swift
+> version: X" paragraph injected. `sources.json`'s `version.descriptive-name`
+> is still validated and recorded in `build-manifest.json`, but nothing reads
+> it to alter documentation content. The mechanics below (verified against
+> `swift-docc` source) remain accurate if this is revisited.
+
 Companion to `hacking-index-json.md` (sidebar/navigator). This file covers the
 **page body** of the combined archive's synthesized landing page
 (`/documentation/`), rendered from `data/documentation.json`, and specifically

scripts/test_build_docs.py

@@ -938,44 +938,6 @@ def fake_run(cmd, **kw):
         self.assertEqual(succeeded, ["combined-merge", "static-hosting-transform"])
         self.assertEqual(failed, [])
 
-    def test_version_paragraph_written_to_landing_page(self):
-        with tempfile.TemporaryDirectory() as tmp:
-            tmp_path = Path(tmp)
-            archive = tmp_path / "a.doccarchive"
-            archive.mkdir()
-            captured = {}
-
-            def fake_run(cmd, **kw):
-                if "merge" in cmd:
-                    out_idx = cmd.index("--output-path") + 1
-                    out = Path(cmd[out_idx])
-                    out.mkdir(parents=True, exist_ok=True)
-                    (out / "index.html").write_text("merged")
-                    _write_landing_page(out, [("Modules", ["doc://Test/documentation/Swift"])])
-                    return subprocess.CompletedProcess(cmd, 0)
-                # transform-for-static-hosting: capture the landing page as it
-                # stood right before docc replaces the archive in place.
-                archive_arg = Path(cmd[cmd.index("transform-for-static-hosting") + 1])
-                captured["doc"] = json.loads(
-                    (archive_arg / "data" / "documentation.json").read_text()
-                )
-                out_idx = cmd.index("--output-path") + 1
-                out = Path(cmd[out_idx])
-                out.mkdir(parents=True, exist_ok=True)
-                (out / "index.html").write_text("transformed")
-                return subprocess.CompletedProcess(cmd, 0)
-
-            with mock.patch.object(build_docs.subprocess, "run", side_effect=fake_run):
-                build_docs._finalize_combined_archive(
-                    [archive], tmp_path, "main", ["docc"], prior_failed=[],
-                    version={"slug": "main", "descriptive-name": "6.3"},
-                )
-
-        self.assertEqual(
-            captured["doc"]["primaryContentSections"][0]["content"][0]["inlineContent"][0]["text"],
-            "Swift version: 6.3",
-        )
-
     def _merge_writes_index(self, modules):
         """Build a fake subprocess.run that writes a merged index.json on merge.
 
@@ -1873,53 +1835,5 @@ def test_landing_page_idempotent(self):
         self.assertEqual(once, twice)
 
 
-class SetVersionParagraph(unittest.TestCase):
-    def test_adds_paragraph_content_section(self):
-        with tempfile.TemporaryDirectory() as tmp:
-            archive = Path(tmp)
-            _write_landing_page(archive, [("Modules", ["doc://Test/documentation/Swift"])])
-            curate_navigator.set_version_paragraph(archive, "Swift version: 6.3")
-            doc = json.loads((archive / "data" / "documentation.json").read_text())
-
-        self.assertEqual(doc["primaryContentSections"], [{
-            "kind": "content",
-            "content": [{
-                "type": "paragraph",
-                "inlineContent": [{"type": "text", "text": "Swift version: 6.3"}],
-            }],
-        }])
-
-    def test_overwrites_existing_primary_content_sections(self):
-        with tempfile.TemporaryDirectory() as tmp:
-            archive = Path(tmp)
-            _write_landing_page(archive, [("Modules", ["doc://Test/documentation/Swift"])])
-            curate_navigator.set_version_paragraph(archive, "Swift version: 6.3")
-            curate_navigator.set_version_paragraph(archive, "Swift version: 6.4")
-            doc = json.loads((archive / "data" / "documentation.json").read_text())
-
-        self.assertEqual(len(doc["primaryContentSections"]), 1)
-        self.assertEqual(
-            doc["primaryContentSections"][0]["content"][0]["inlineContent"][0]["text"],
-            "Swift version: 6.4",
-        )
-
-    def test_preserves_topic_sections_and_references(self):
-        with tempfile.TemporaryDirectory() as tmp:
-            archive = Path(tmp)
-            _write_landing_page(archive, [("Modules", ["doc://Test/documentation/Swift"])])
-            before = json.loads((archive / "data" / "documentation.json").read_text())
-            curate_navigator.set_version_paragraph(archive, "Swift version: 6.3")
-            after = json.loads((archive / "data" / "documentation.json").read_text())
-
-        self.assertEqual(after["topicSections"], before["topicSections"])
-        self.assertEqual(after["references"], before["references"])
-
-    def test_missing_landing_page_is_noop(self):
-        with tempfile.TemporaryDirectory() as tmp:
-            archive = Path(tmp)
-            curate_navigator.set_version_paragraph(archive, "Swift version: 6.3")
-            self.assertFalse((archive / "data" / "documentation.json").exists())
-
-
 if __name__ == "__main__":
     unittest.main()