diff --git a/scripts/build_docs.py b/scripts/build_docs.py index 2aa99f4f..3e23b143 100755 --- a/scripts/build_docs.py +++ b/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) diff --git a/scripts/curate_navigator.py b/scripts/curate_navigator.py index 071cf8e2..a773075a 100644 --- a/scripts/curate_navigator.py +++ b/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. diff --git a/scripts/hacking-synthesized-landing-page.md b/scripts/hacking-synthesized-landing-page.md index 0be73511..6f4075b8 100644 --- a/scripts/hacking-synthesized-landing-page.md +++ b/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 diff --git a/scripts/test_build_docs.py b/scripts/test_build_docs.py index 1bb6530a..c5f6a3c7 100644 --- a/scripts/test_build_docs.py +++ b/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() \ No newline at end of file