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

chore(release): 0.0.7

Browse Source 
Squash-merge lib-standardisation: adopt repo standards across packaging,
tooling, docs, and CI.

- standardize pyproject.toml (canonical packaging, lint config, extras, GSDFC pydoclint)
- add py.typed marker, modernize type hints and Google-style docstrings
- nest generated docs under docs/lib and docs/mcp; add hand-written wiki
- adopt standard Type A PyPI CI pipeline (tag==version guard + quality gate)
- promote generated CHANGELOG.md; bump version to 0.0.7
This commit is contained in:
Vishesh 'ironeagle' Bangotra
2026-10-17 02:16:44 +05:30
parent 8253c25928
commit 06ffd2febd
149 changed files with 7132 additions and 4594 deletions
Download Patch File Download Diff File Expand all files Collapse all files

142
tests/cli/test_build_api.py Normal file
View File

@@ -0,0 +1,142 @@
import json
from pathlib import Path
from docforge.cli.main import cli
def _write_spec(cwd, title="Aetoskia Auth Server", description="Auth docs"):
spec = {
"openapi": "3.1.0",
"info": {
"title": title,
"description": description,
"contact": {
"name": "Aetoskia Dev Team",
"email": "dev@aetoskia.com",
},
"version": "0.0.5",
},
"paths": {},
}
path = cwd / "openapi.json"
path.write_text(json.dumps(spec), encoding="utf-8")
return path
def test_api_build_full_flow(
cli_runner,
mock_mkdocs_build,
mock_mkdocs_load_config,
):
with cli_runner.isolated_filesystem():
cwd = Path.cwd()
spec_path = _write_spec(cwd)
nav_file = cwd / "docforge.nav.yml"
nav_file.write_text(
"home: api/index.md\ngroups: {}\n"
"icon:\n"
" logo: material/database\n"
" repo: fontawesome/brands/github\n",
encoding="utf-8",
)
result = cli_runner.invoke(
cli,
["build", "--api", "--openapi-spec", str(spec_path)],
)
assert result.exit_code == 0, result.output
assert mock_mkdocs_build() is True
api_dir = cwd / "docs" / "api"
assert (api_dir / "openapi.json").exists()
index = (api_dir / "index.md").read_text(encoding="utf-8")
assert '<swagger-ui src="openapi.json"/>' in index
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
assert "swagger-ui-tag" in config
assert "logo: material/database" in config
assert "repo: fontawesome/brands/github" in config
def test_api_build_missing_spec_fails(cli_runner):
result = cli_runner.invoke(cli, ["build", "--api"])
assert result.exit_code != 0
assert "--openapi-spec is required" in result.output
def test_api_build_spec_not_found(cli_runner):
result = cli_runner.invoke(cli, ["build", "--api", "--openapi-spec", "nope.json"])
assert result.exit_code != 0
assert "OpenAPI spec not found" in result.output
def test_api_build_rejects_site_name_override(cli_runner):
with cli_runner.isolated_filesystem():
cwd = Path.cwd()
spec_path = _write_spec(cwd)
result = cli_runner.invoke(
cli,
["build", "--api", "--openapi-spec", str(spec_path), "--site-name", "X"],
)
assert result.exit_code != 0
assert "cannot be overridden" in result.output
def test_api_build_combined_with_mkdocs_emits_separate_configs(
cli_runner, mock_mkdocs_build, mock_mkdocs_load_config
):
with cli_runner.isolated_filesystem():
cwd = Path.cwd()
pkg = cwd / "testpkg"
pkg.mkdir()
(pkg / "__init__.py").write_text("")
(pkg / "mod.py").write_text("def f(): ...\n")
spec_path = _write_spec(cwd)
nav_file = cwd / "docforge.nav.yml"
nav_file.write_text("home: lib/testpkg/index.md\ngroups: {}\n")
result = cli_runner.invoke(
cli,
[
"build",
"--mkdocs",
"--api",
"--module",
"testpkg",
"--openapi-spec",
str(spec_path),
],
)
assert result.exit_code == 0, result.output
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

6
tests/cli/test_build_mcp.py
View File

@@ -1,6 +1,8 @@
from pathlib import Path
from docforge.cli.main import cli
def test_mcp_build(cli_runner):
with cli_runner.isolated_filesystem():
cwd = Path.cwd()
@@ -9,7 +11,7 @@ def test_mcp_build(cli_runner):
(pkg / "__init__.py").write_text("")
(pkg / "mod.py").write_text("def f(): ...\n")
out_dir = cwd / "mcp_docs"
out_dir = cwd / "docs" / "mcp"
result = cli_runner.invoke(
cli,
@@ -18,8 +20,6 @@ def test_mcp_build(cli_runner):
"--mcp",
"--module",
"testpkg",
"--out-dir",
str(out_dir),
],
)

123
tests/cli/test_build_mkdocs.py
View File

@@ -1,6 +1,8 @@
from pathlib import Path
from docforge.cli.main import cli
def test_mkdocs_build_full_flow(
cli_runner,
mock_mkdocs_build,
@@ -16,12 +18,8 @@ def test_mkdocs_build_full_flow(
(pkg / "mod.py").write_text("def f(): ...\n")
nav_file = cwd / "docforge.nav.yml"
nav_file.write_text("home: 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.
nav_file.write_text("home: lib/testpkg/index.md\ngroups: {}\n")
result = cli_runner.invoke(
cli,
[
@@ -31,23 +29,27 @@ def test_mkdocs_build_full_flow(
"testpkg",
"--site-name",
"Test Site",
"--docs-dir",
"docs",
"--mkdocs-yml",
"mkdocs.yml",
],
)
assert result.exit_code == 0
assert mock_mkdocs_build() is True
assert (cwd / "mkdocs.yml").exists()
assert (cwd / "docs" / "testpkg" / "mod.md").exists()
config = cwd / "docs" / "mkdocs.lib.yml"
assert config.exists()
assert (cwd / "docs" / "lib" / "testpkg" / "mod.md").exists()
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):
result = cli_runner.invoke(cli, ["build", "--mkdocs", "--site-name", "Test"])
assert result.exit_code != 0
assert "--module is required" in result.output
def test_mkdocs_build_without_site_name_uses_module_as_default_full_flow(
cli_runner,
mock_mkdocs_build,
@@ -63,37 +65,98 @@ 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: testpkg/index.md\ngroups: {}\n",
"home: lib/testpkg/index.md\ngroups: {}\n",
encoding="utf-8",
)
result = cli_runner.invoke(
cli,
[
"build",
"--mkdocs",
"--module",
"testpkg",
"--docs-dir",
"docs",
"--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
assert (cwd / "docs" / "testpkg" / "mod.md").exists()
# Docs must be generated under the nested docs/lib dir
assert (cwd / "docs" / "lib" / "testpkg" / "mod.md").exists()
def test_existing_lib_config_used_verbatim_without_refresh(
cli_runner,
mock_mkdocs_build,
mock_mkdocs_load_config,
):
with cli_runner.isolated_filesystem():
cwd = Path.cwd()
pkg = cwd / "testpkg"
pkg.mkdir()
(pkg / "__init__.py").write_text("")
(pkg / "mod.py").write_text("def f(): ...\n")
nav_file = cwd / "docforge.nav.yml"
nav_file.write_text(
"home: lib/testpkg/index.md\ngroups: {}\n",
encoding="utf-8",
)
config = cwd / "docs" / "mkdocs.lib.yml"
config.parent.mkdir(parents=True)
sentinel = "site_name: Custom Lib\nnav: []\n"
config.write_text(sentinel, encoding="utf-8")
result = cli_runner.invoke(
cli,
["build", "--mkdocs", "--module", "testpkg"],
)
assert result.exit_code == 0, result.output
assert mock_mkdocs_build() is True
assert config.read_text(encoding="utf-8") == sentinel
assert "Using existing MkDocs config" in result.output
def test_refresh_rebases_existing_lib_config(
cli_runner,
mock_mkdocs_build,
mock_mkdocs_load_config,
):
with cli_runner.isolated_filesystem():
cwd = Path.cwd()
pkg = cwd / "testpkg"
pkg.mkdir()
(pkg / "__init__.py").write_text("")
(pkg / "mod.py").write_text("def f(): ...\n")
nav_file = cwd / "docforge.nav.yml"
nav_file.write_text(
"home: lib/testpkg/index.md\ngroups: {}\n",
encoding="utf-8",
)
config = cwd / "docs" / "mkdocs.lib.yml"
config.parent.mkdir(parents=True)
config.write_text("site_name: Stale\nnav: []\n", encoding="utf-8")
result = cli_runner.invoke(
cli,
["build", "--mkdocs", "--module", "testpkg", "--refresh"],
)
assert result.exit_code == 0, result.output
assert mock_mkdocs_build() is True
content = config.read_text(encoding="utf-8")
assert "site_name: testpkg" in content
assert "docs_dir: lib" in content
assert "site_dir: ../site/lib" in content
assert "Home: testpkg/index.md" in content

165
tests/cli/test_build_wiki.py Normal file
View File

@@ -0,0 +1,165 @@
from pathlib import Path
from docforge.cli.main import cli
def test_wiki_only_build_requires_no_module(
cli_runner,
mock_mkdocs_build,
mock_mkdocs_load_config,
):
with cli_runner.isolated_filesystem():
cwd = Path.cwd()
wiki = cwd / "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")
result = cli_runner.invoke(
cli,
[
"build",
"--wiki",
"--site-name",
"Wiki Site",
],
)
assert result.exit_code == 0, result.output
assert mock_mkdocs_build() is True
config = cwd / "docs" / "mkdocs.wiki.yml"
assert config.exists()
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_and_mkdocs_emit_separate_configs(
cli_runner,
mock_mkdocs_build,
mock_mkdocs_load_config,
):
with cli_runner.isolated_filesystem():
cwd = Path.cwd()
pkg = cwd / "testpkg"
pkg.mkdir()
(pkg / "__init__.py").write_text("")
(pkg / "mod.py").write_text("def f(): ...\n")
nav_file = cwd / "docforge.nav.yml"
nav_file.write_text(
"home: lib/testpkg/index.md\ngroups: {}\n",
encoding="utf-8",
)
wiki = cwd / "docs" / "wiki"
wiki.mkdir(parents=True)
(wiki / "index.md").write_text("# Home", encoding="utf-8")
result = cli_runner.invoke(
cli,
[
"build",
"--mkdocs",
"--wiki",
"--module",
"testpkg",
"--site-name",
"Split Site",
],
)
assert result.exit_code == 0, result.output
assert mock_mkdocs_build() is True
assert (cwd / "docs" / "lib" / "testpkg" / "mod.md").exists()
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(
cli_runner,
mock_mkdocs_build,
mock_mkdocs_load_config,
):
with cli_runner.isolated_filesystem():
cwd = Path.cwd()
wiki = cwd / "docs" / "wiki"
wiki.mkdir(parents=True)
(wiki / "index.md").write_text("# Home", encoding="utf-8")
result = cli_runner.invoke(
cli,
["build", "--wiki", "--site-name", "S"],
)
assert result.exit_code == 0, result.output
assert mock_mkdocs_build() is True
def test_wiki_existing_config_used_verbatim_without_refresh(
cli_runner,
mock_mkdocs_build,
mock_mkdocs_load_config,
):
with cli_runner.isolated_filesystem():
cwd = Path.cwd()
wiki = cwd / "docs" / "wiki"
wiki.mkdir(parents=True)
(wiki / "index.md").write_text("# Home", encoding="utf-8")
config = cwd / "docs" / "mkdocs.wiki.yml"
sentinel = "site_name: Custom Wiki\nnav: []\n"
config.write_text(sentinel, encoding="utf-8")
result = cli_runner.invoke(
cli,
["build", "--wiki", "--site-name", "Wiki Site"],
)
assert result.exit_code == 0, result.output
assert mock_mkdocs_build() is True
assert config.read_text(encoding="utf-8") == sentinel
assert "Using existing MkDocs config" in result.output
def test_missing_wiki_dir_errors(cli_runner, mock_mkdocs_build):
with cli_runner.isolated_filesystem():
cwd = Path.cwd()
(cwd / "docs").mkdir()
result = cli_runner.invoke(
cli,
[
"build",
"--wiki",
"--site-name",
"S",
"--wiki-dir",
"docs/wiki",
],
)
assert result.exit_code != 0
assert "Wiki dir not found" in result.output
def test_no_flag_raises_usage_error(cli_runner):
result = cli_runner.invoke(cli, ["build"])
assert result.exit_code != 0
assert "--mcp, --mkdocs, --wiki, or --api" in result.output

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

1
tests/cli/test_serve_mcp.py
View File

@@ -1,5 +1,6 @@
from docforge.cli.main import cli
def test_mcp_serve(
cli_runner,
fake_mcp_docs,

1
tests/cli/test_serve_mkdocs.py
View File

@@ -1,5 +1,6 @@
from docforge.cli.main import cli
def test_mkdocs_serve(
cli_runner,
fake_mkdocs_yml,