feat: add wiki build kind with file-structure-derived navigation
- add build_wiki_nav deriving MkDocs nav from docs/wiki file structure (index.md -> Home, numeric prefixes stripped and title-cased, nested dirs become groups, natural ordering) - add --wiki / --wiki-dir to build; wiki-only builds need no --module - merge wiki nav before generated lib/api nav; wiki Home replaces the nav spec Home entry - add mkdocs.wiki.yml template fragment and nav/cli tests - dogfood doc-forge's own docs/wiki and regenerate site output
This commit is contained in:
106
tests/nav/test_wiki.py
Normal file
106
tests/nav/test_wiki.py
Normal file
@@ -0,0 +1,106 @@
|
||||
from pathlib import Path
|
||||
|
||||
import pytest
|
||||
|
||||
from docforge.nav import build_wiki_nav
|
||||
|
||||
|
||||
def _write_wiki(root: Path, files: list[str]) -> None:
|
||||
for rel in files:
|
||||
full = root / rel
|
||||
full.parent.mkdir(parents=True, exist_ok=True)
|
||||
full.write_text(f"# {rel}", encoding="utf-8")
|
||||
|
||||
|
||||
def test_missing_wiki_dir_raises(tmp_path: Path):
|
||||
with pytest.raises(FileNotFoundError):
|
||||
build_wiki_nav(tmp_path / "nope")
|
||||
|
||||
|
||||
def test_empty_wiki_dir_returns_empty(tmp_path: Path):
|
||||
wiki = tmp_path / "wiki"
|
||||
wiki.mkdir()
|
||||
|
||||
assert build_wiki_nav(wiki) == []
|
||||
|
||||
|
||||
def test_index_becomes_home(tmp_path: Path):
|
||||
wiki = tmp_path / "docs" / "wiki"
|
||||
_write_wiki(wiki, ["index.md", "01_overview.md"])
|
||||
|
||||
nav = build_wiki_nav(wiki)
|
||||
|
||||
assert nav[0] == {"Home": "wiki/index.md"}
|
||||
assert {"Overview": "wiki/01_overview.md"} in nav
|
||||
|
||||
|
||||
def test_number_prefix_stripped_and_prettified(tmp_path: Path):
|
||||
wiki = tmp_path / "docs" / "wiki"
|
||||
_write_wiki(wiki, ["01_basic_crud.md", "02_custom_repo.md", "10_transactions.md"])
|
||||
|
||||
nav = build_wiki_nav(wiki)
|
||||
|
||||
labels = [list(entry)[0] for entry in nav]
|
||||
assert labels == ["Basic Crud", "Custom Repo", "Transactions"]
|
||||
|
||||
|
||||
def test_directory_becomes_nested_group(tmp_path: Path):
|
||||
wiki = tmp_path / "docs" / "wiki"
|
||||
_write_wiki(
|
||||
wiki,
|
||||
[
|
||||
"index.md",
|
||||
"03_use_cases/01_basic_crud.md",
|
||||
"03_use_cases/02_custom_repo.md",
|
||||
],
|
||||
)
|
||||
|
||||
nav = build_wiki_nav(wiki)
|
||||
|
||||
assert {"Home": "wiki/index.md"} in nav
|
||||
assert {
|
||||
"Use Cases": [
|
||||
{"Basic Crud": "wiki/03_use_cases/01_basic_crud.md"},
|
||||
{"Custom Repo": "wiki/03_use_cases/02_custom_repo.md"},
|
||||
]
|
||||
} in nav
|
||||
|
||||
|
||||
def test_nested_index_is_section_root(tmp_path: Path):
|
||||
wiki = tmp_path / "docs" / "wiki"
|
||||
_write_wiki(
|
||||
wiki,
|
||||
[
|
||||
"guide/index.md",
|
||||
"guide/01_setup.md",
|
||||
],
|
||||
)
|
||||
|
||||
nav = build_wiki_nav(wiki)
|
||||
|
||||
assert {
|
||||
"Guide": [
|
||||
{"Guide": "wiki/guide/index.md"},
|
||||
{"Setup": "wiki/guide/01_setup.md"},
|
||||
]
|
||||
} in nav
|
||||
|
||||
|
||||
def test_hidden_entries_ignored(tmp_path: Path):
|
||||
wiki = tmp_path / "docs" / "wiki"
|
||||
_write_wiki(wiki, ["index.md", ".draft.md"])
|
||||
(wiki / ".hidden").mkdir()
|
||||
|
||||
nav = build_wiki_nav(wiki)
|
||||
|
||||
assert nav == [{"Home": "wiki/index.md"}]
|
||||
|
||||
|
||||
def test_natural_order_for_zero_padded_prefixes(tmp_path: Path):
|
||||
wiki = tmp_path / "docs" / "wiki"
|
||||
_write_wiki(wiki, ["02_b.md", "10_j.md", "01_a.md"])
|
||||
|
||||
nav = build_wiki_nav(wiki)
|
||||
|
||||
labels = [list(entry)[0] for entry in nav if list(entry)[0] in {"A", "B", "J"}]
|
||||
assert labels == ["A", "B", "J"]
|
||||
Reference in New Issue
Block a user