tests/renderers/mkdocs/test_mkdocs_content.py

@@ -17,3 +17,34 @@ def test_mkdocs_file_content(tmp_path: Path):
 
     assert "# Mod" in content
     assert "::: testpkg.mod" in content
+
+
+def test_generate_readme_source_root(tmp_path: Path):
+    project = Project("testpkg")
+
+    root = Module("testpkg")
+    root.docstring = "Test package documentation."
+
+    project.add_module(root)
+    project.add_module(Module("testpkg.mod"))
+
+    docs_dir = tmp_path / "docs"
+
+    renderer = MkDocsRenderer()
+
+    renderer.generate_sources(project, docs_dir)
+
+    renderer.generate_readme(
+        project,
+        docs_dir,
+        module_is_source=True,
+    )
+
+    readme = tmp_path / "README.md"
+
+    assert readme.exists()
+
+    content = readme.read_text()
+
+    assert "# testpkg" in content
+    assert "Test package documentation." in content

tests/renderers/mkdocs/test_mkdocs_idempotency.py

@@ -18,3 +18,36 @@ def test_mkdocs_idempotent(tmp_path: Path):
     second = (out_dir / "testpkg" / "mod.md").read_text()
 
     assert first == second
+
+
+def test_generate_readme_idempotent(tmp_path: Path):
+    project = Project("testpkg")
+
+    root = Module("testpkg")
+    root.docstring = "Test package documentation."
+
+    project.add_module(root)
+
+    docs_dir = tmp_path / "docs"
+
+    renderer = MkDocsRenderer()
+
+    renderer.generate_readme(
+        project,
+        docs_dir,
+        module_is_source=True,
+    )
+
+    readme = tmp_path / "README.md"
+
+    first = readme.read_text()
+
+    renderer.generate_readme(
+        project,
+        docs_dir,
+        module_is_source=True,
+    )
+
+    second = readme.read_text()
+
+    assert first == second

tests/renderers/mkdocs/test_mkdocs_module_coverage.py

@@ -17,6 +17,12 @@ def test_mkdocs_emits_all_modules(tmp_path: Path) -> None:
     renderer = MkDocsRenderer()
     renderer.generate_sources(project, tmp_path)
 
+    renderer.generate_readme(
+        project,
+        tmp_path,
+        module_is_source=True,
+    )
+
     emitted = {
         p.relative_to(tmp_path).as_posix()
         for p in tmp_path.rglob("*.md")
@@ -39,3 +45,8 @@ def test_mkdocs_emits_all_modules(tmp_path: Path) -> None:
 
     missing = expected - emitted
     assert not missing, f"Missing markdown files for modules: {missing}"
+
+    readme = tmp_path.parent / "README.md"
+    assert readme.exists(), "README.md was not generated"
+    content = readme.read_text(encoding="utf-8")
+    assert project.name in content

tests/renderers/mkdocs/test_mkdocs_structure.py

@@ -13,6 +13,12 @@ def test_mkdocs_directory_structure(tmp_path: Path):
     renderer = MkDocsRenderer()
 
     renderer.generate_sources(project, out_dir)
+    renderer.generate_readme(
+        project,
+        out_dir,
+        module_is_source=True,
+    )
 
     assert (out_dir / "testpkg" / "index.md").exists()
     assert (out_dir / "testpkg" / "sub.md").exists()
+    assert (tmp_path / "README.md").exists()