aetos/doc-forge
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: build each doc kind with its own MkDocs config and site

Browse Source
This commit is contained in:
Vishesh 'ironeagle' Bangotra
2026-09-12 14:23:22 +05:30
parent 582b6809a0
commit 2ae96f58de
21 changed files with 942 additions and 443 deletions
Download Patch File Download Diff File Expand all files Collapse all files

40
tests/cli/test_build_api.py
View File

@@ -1,4 +1,4 @@
import json
import json
from pathlib import Path
from docforge.cli.main import cli
@@ -55,8 +55,10 @@ def test_api_build_full_flow(
index = (api_dir / "index.md").read_text(encoding="utf-8")
assert '<swagger-ui src="openapi.json"/>' in index
config = (cwd / "mkdocs.yml").read_text(encoding="utf-8")
assert "docs_dir: docs" in config
config = (cwd / "docs" / "mkdocs.api.yml").read_text(encoding="utf-8")
assert "docs_dir: api" in config
assert "site_dir: ../site/api" in config
assert "- API Reference: index.md" in config
assert "site_name: Aetoskia Auth Server" in config
assert "site_description: Auth docs" in config
assert "site_author: Aetoskia Dev Team" in config
@@ -90,10 +92,9 @@ def test_api_build_rejects_site_name_override(cli_runner):
assert "cannot be overridden" in result.output
def test_api_build_combined_with_mkdocs_allows_site_name_for_lib(
def test_api_build_combined_with_mkdocs_emits_separate_configs(
cli_runner, mock_mkdocs_build, mock_mkdocs_load_config
):
# site_name is accepted when --mkdocs is also present (lib mode owns it)
with cli_runner.isolated_filesystem():
cwd = Path.cwd()
@@ -105,13 +106,7 @@ def test_api_build_combined_with_mkdocs_allows_site_name_for_lib(
spec_path = _write_spec(cwd)
nav_file = cwd / "docforge.nav.yml"
nav_file.write_text(
"home: lib/testpkg/index.md\n"
"groups:\n"
" API:\n"
" - api/index.md\n",
encoding="utf-8",
)
nav_file.write_text("home: lib/testpkg/index.md\ngroups: {}\n")
result = cli_runner.invoke(
cli,
@@ -128,7 +123,20 @@ def test_api_build_combined_with_mkdocs_allows_site_name_for_lib(
assert result.exit_code == 0, result.output
config = (cwd / "mkdocs.yml").read_text(encoding="utf-8")
assert "docs_dir: docs" in config
assert "swagger-ui-tag" in config
assert "mkdocstrings" in config
lib_config = cwd / "docs" / "mkdocs.lib.yml"
api_config = cwd / "docs" / "mkdocs.api.yml"
assert lib_config.exists()
assert api_config.exists()
lib_text = lib_config.read_text(encoding="utf-8")
assert "docs_dir: lib" in lib_text
assert "site_dir: ../site/lib" in lib_text
assert "Home: testpkg/index.md" in lib_text
api_text = api_config.read_text(encoding="utf-8")
assert "docs_dir: api" in api_text
assert "site_dir: ../site/api" in api_text
assert "- API Reference: index.md" in api_text
assert "site_name: Aetoskia Auth Server" in api_text
assert "swagger-ui-tag" in api_text
assert "mkdocstrings" in lib_text

34
tests/cli/test_build_mkdocs.py
View File

@@ -20,10 +20,6 @@ def test_mkdocs_build_full_flow(
nav_file = cwd / "docforge.nav.yml"
nav_file.write_text("home: lib/testpkg/index.md\ngroups: {}\n")
# We need to create a dummy testpkg/index.md for nav resolution if it's there
# But generate_sources will create it.
# Wait, the current logic runs generate_sources first, THEN generate_config.
result = cli_runner.invoke(
cli,
[
@@ -33,16 +29,19 @@ def test_mkdocs_build_full_flow(
"testpkg",
"--site-name",
"Test Site",
"--mkdocs-yml",
"mkdocs.yml",
],
)
assert result.exit_code == 0
assert mock_mkdocs_build() is True
assert (cwd / "mkdocs.yml").exists()
config = cwd / "docs" / "mkdocs.lib.yml"
assert config.exists()
assert (cwd / "docs" / "lib" / "testpkg" / "mod.md").exists()
assert "docs_dir: docs" in (cwd / "mkdocs.yml").read_text()
content = config.read_text(encoding="utf-8")
assert "docs_dir: lib" in content
assert "site_dir: ../site/lib" in content
assert "Home: testpkg/index.md" in content
def test_mkdocs_build_missing_module_fails(cli_runner):
@@ -66,7 +65,7 @@ def test_mkdocs_build_without_site_name_uses_module_as_default_full_flow(
(pkg / "__init__.py").write_text("")
(pkg / "mod.py").write_text("def f(): ...\n")
# Create nav spec expected by generate_config
# Create nav spec expected by build_lib_nav
nav_file = cwd / "docforge.nav.yml"
nav_file.write_text(
"home: lib/testpkg/index.md\ngroups: {}\n",
@@ -75,25 +74,18 @@ def test_mkdocs_build_without_site_name_uses_module_as_default_full_flow(
result = cli_runner.invoke(
cli,
[
"build",
"--mkdocs",
"--module",
"testpkg",
"--mkdocs-yml",
"mkdocs.yml",
],
["build", "--mkdocs", "--module", "testpkg"],
)
assert result.exit_code == 0
assert mock_mkdocs_build() is True
# MkDocs config must exist
mkdocs_yml = cwd / "mkdocs.yml"
assert mkdocs_yml.exists()
# The per-kind MkDocs config must exist
config = cwd / "docs" / "mkdocs.lib.yml"
assert config.exists()
# Site name must default to module name
content = mkdocs_yml.read_text()
content = config.read_text(encoding="utf-8")
assert "site_name: testpkg" in content
# Docs must be generated under the nested docs/lib dir

37
tests/cli/test_build_wiki.py
View File

@@ -23,22 +23,22 @@ def test_wiki_only_build_requires_no_module(
"--wiki",
"--site-name",
"Wiki Site",
"--mkdocs-yml",
"mkdocs.yml",
],
)
assert result.exit_code == 0, result.output
assert mock_mkdocs_build() is True
assert (cwd / "mkdocs.yml").exists()
config = cwd / "docs" / "mkdocs.wiki.yml"
assert config.exists()
content = (cwd / "mkdocs.yml").read_text(encoding="utf-8")
assert "docs_dir: docs" in content
assert "Home: wiki/index.md" in content
assert "Overview: wiki/01_overview.md" in content
content = config.read_text(encoding="utf-8")
assert "docs_dir: wiki" in content
assert "site_dir: ../site/wiki" in content
assert "Home: index.md" in content
assert "Overview: 01_overview.md" in content
def test_wiki_combined_with_mkdocs_keeps_lib_nav(
def test_wiki_and_mkdocs_emit_separate_configs(
cli_runner,
mock_mkdocs_build,
mock_mkdocs_load_config,
@@ -70,9 +70,7 @@ def test_wiki_combined_with_mkdocs_keeps_lib_nav(
"--module",
"testpkg",
"--site-name",
"Combined Site",
"--mkdocs-yml",
"mkdocs.yml",
"Split Site",
],
)
@@ -80,11 +78,16 @@ def test_wiki_combined_with_mkdocs_keeps_lib_nav(
assert mock_mkdocs_build() is True
assert (cwd / "docs" / "lib" / "testpkg" / "mod.md").exists()
content = (cwd / "mkdocs.yml").read_text(encoding="utf-8")
assert "docs_dir: docs" in content
assert "Home: wiki/index.md" in content
# Wiki home replaces the lib home entry
assert "Home: lib/testpkg/index.md" not in content
lib_config = (cwd / "docs" / "mkdocs.lib.yml").read_text(encoding="utf-8")
wiki_config = (cwd / "docs" / "mkdocs.wiki.yml").read_text(encoding="utf-8")
assert "docs_dir: lib" in lib_config
assert "site_dir: ../site/lib" in lib_config
assert "Home: testpkg/index.md" in lib_config
assert "docs_dir: wiki" in wiki_config
assert "site_dir: ../site/wiki" in wiki_config
assert "Home: index.md" in wiki_config
def test_wiki_without_module_flag_ok(
@@ -122,8 +125,6 @@ def test_missing_wiki_dir_errors(cli_runner, mock_mkdocs_build):
"S",
"--wiki-dir",
"docs/wiki",
"--mkdocs-yml",
"mkdocs.yml",
],
)

79
tests/cli/test_mkdocs_utils.py Normal file
View File

@@ -0,0 +1,79 @@
import pytest
from click.exceptions import FileError
from docforge.cli.mkdocs_utils import (
_strip_scope,
build_lib_nav,
build_wiki_nav_block,
load_spec_icon,
)
def test_strip_scope_nested_entries():
block = [
{"Home": "wiki/index.md"},
{
"Development": [
{"Environment": "wiki/05_development/01_environment.md"},
"wiki/05_development/02_quality_gates.md",
]
},
]
stripped = _strip_scope(block, "wiki")
assert stripped == [
{"Home": "index.md"},
{
"Development": [
{"Environment": "05_development/01_environment.md"},
"05_development/02_quality_gates.md",
]
},
]
def test_strip_scope_leaves_unscoped_paths():
block = [{"Other": "static/pages.md"}]
assert _strip_scope(block, "lib") == [{"Other": "static/pages.md"}]
def test_build_lib_nav_reroots_group_paths(tmp_path):
docs = tmp_path / "docs"
lib = docs / "lib" / "testpkg"
lib.mkdir(parents=True)
(lib / "index.md").write_text("# Pkg", encoding="utf-8")
(lib / "mod.md").write_text("# Mod", encoding="utf-8")
nav_file = tmp_path / "docforge.nav.yml"
nav_file.write_text(
"home: lib/testpkg/index.md\n"
"groups:\n"
" Reference:\n"
" - lib/testpkg/mod.md\n",
encoding="utf-8",
)
block, icon = build_lib_nav(nav_file, docs)
assert block == [{"Home": "testpkg/index.md"}, {"Reference": ["testpkg/mod.md"]}]
assert icon is None
def test_build_lib_nav_missing_spec_raises(tmp_path):
with pytest.raises(FileError):
build_lib_nav(tmp_path / "missing.yml", tmp_path)
def test_build_wiki_nav_block_reroots_entries(tmp_path):
wiki = tmp_path / "docs" / "wiki"
wiki.mkdir(parents=True)
(wiki / "index.md").write_text("# Home", encoding="utf-8")
(wiki / "01_overview.md").write_text("# Overview", encoding="utf-8")
block = build_wiki_nav_block(wiki)
assert block == [{"Home": "index.md"}, {"Overview": "01_overview.md"}]
def test_load_spec_icon(tmp_path):
nav_file = tmp_path / "docforge.nav.yml"
nav_file.write_text("home: index.md\nicon:\n logo: material/code-tags\n")
assert load_spec_icon(nav_file) == {"logo": "material/code-tags"}
assert load_spec_icon(tmp_path / "missing.yml") is None