standardize packaging, tooling, docs, CI, and licensing

docforge/cli/__init__.py

@@ -37,6 +37,4 @@ Example:
 
 from .main import main
 
-__all__ = [
-    "main"
-]
+__all__ = ["main"]

docforge/cli/__init__.pyi

@@ -1,5 +1,3 @@
 from .main import main
 
-__all__ = [
-    "main"
-]
+__all__ = ["main"]

docforge/cli/commands.py

@@ -6,12 +6,12 @@ Command definitions for the doc-forge CLI.
 Provides the CLI structure using Click, including build, serve, and tree commands.
 """
 
-import click
 from pathlib import Path
-from typing import Sequence, Optional
+
+import click
+
+from docforge.cli import mcp_utils, mkdocs_utils
 from docforge.loaders import GriffeLoader
-from docforge.cli import mkdocs_utils
-from docforge.cli import mcp_utils
 
 
 @click.group()
@@ -28,26 +28,52 @@ def cli() -> None:
 @cli.command()
 @click.option("--mcp", is_flag=True, help="Build MCP resources")
 @click.option("--mkdocs", is_flag=True, help="Build MkDocs site")
-@click.option("--module-is-source", is_flag=True, help="Module is source folder and to be treated as root folder")
+@click.option(
+    "--module-is-source",
+    is_flag=True,
+    help="Module is source folder and to be treated as root folder",
+)
 @click.option("--module", help="Python module to document")
 @click.option("--project-name", help="Project name override")
 @click.option("--site-name", help="MkDocs site name")
-@click.option("--docs-dir", type=click.Path(path_type=Path), default=Path("docs"), help="Directory for MD sources")
-@click.option("--nav", "nav_file", type=click.Path(path_type=Path), default=Path("docforge.nav.yml"),
-              help="Nav spec path")
-@click.option("--template", type=click.Path(path_type=Path), help="MkDocs template path")
-@click.option("--mkdocs-yml", type=click.Path(path_type=Path), default=Path("mkdocs.yml"), help="Output config path")
-@click.option("--out-dir", type=click.Path(path_type=Path), default=Path("mcp_docs"), help="MCP output directory")
+@click.option(
+    "--docs-dir",
+    type=click.Path(path_type=Path),
+    default=Path("docs"),
+    help="Directory for MD sources",
+)
+@click.option(
+    "--nav",
+    "nav_file",
+    type=click.Path(path_type=Path),
+    default=Path("docforge.nav.yml"),
+    help="Nav spec path",
+)
+@click.option(
+    "--template", type=click.Path(path_type=Path), help="MkDocs template path"
+)
+@click.option(
+    "--mkdocs-yml",
+    type=click.Path(path_type=Path),
+    default=Path("mkdocs.yml"),
+    help="Output config path",
+)
+@click.option(
+    "--out-dir",
+    type=click.Path(path_type=Path),
+    default=Path("mcp_docs"),
+    help="MCP output directory",
+)
 def build(
     mcp: bool,
     mkdocs: bool,
     module_is_source: bool,
-    module: Optional[str],
-    project_name: Optional[str],
-    site_name: Optional[str],
+    module: str | None,
+    project_name: str | None,
+    site_name: str | None,
     docs_dir: Path,
     nav_file: Path,
-    template: Optional[Path],
+    template: Path | None,
     mkdocs_yml: Path,
     out_dir: Path,
 ) -> None:
@@ -121,7 +147,9 @@ def build(
         )
 
         click.echo(f"Generating MkDocs config {mkdocs_yml}...")
-        mkdocs_utils.generate_config(docs_dir, nav_file, template, mkdocs_yml, site_name)
+        mkdocs_utils.generate_config(
+            docs_dir, nav_file, template, mkdocs_yml, site_name
+        )
 
         click.echo("Running MkDocs build...")
         mkdocs_utils.build(mkdocs_yml)
@@ -140,12 +168,22 @@ def build(
 @click.option("--mcp", is_flag=True, help="Serve MCP documentation")
 @click.option("--mkdocs", is_flag=True, help="Serve MkDocs site")
 @click.option("--module", help="Python module to serve")
-@click.option("--mkdocs-yml", type=click.Path(path_type=Path), default=Path("mkdocs.yml"), help="MkDocs config path")
-@click.option("--out-dir", type=click.Path(path_type=Path), default=Path("mcp_docs"), help="MCP root directory")
+@click.option(
+    "--mkdocs-yml",
+    type=click.Path(path_type=Path),
+    default=Path("mkdocs.yml"),
+    help="MkDocs config path",
+)
+@click.option(
+    "--out-dir",
+    type=click.Path(path_type=Path),
+    default=Path("mcp_docs"),
+    help="MCP root directory",
+)
 def serve(
     mcp: bool,
     mkdocs: bool,
-    module: Optional[str],
+    module: str | None,
     mkdocs_yml: Path,
     out_dir: Path,
 ) -> None:
@@ -202,7 +240,7 @@ def serve(
 )
 def tree(
     module: str,
-    project_name: Optional[str],
+    project_name: str | None,
 ) -> None:
     """
     Display the documentation object tree for a module.

docforge/cli/commands.pyi

@@ -1,6 +1,7 @@
-from click.core import Group
 from pathlib import Path
-from typing import Sequence, Optional, Any
+from typing import Any
+
+from click.core import Group
 
 cli: Group
 
@@ -8,27 +9,24 @@ def build(
     mcp: bool,
     mkdocs: bool,
     module_is_source: bool,
-    module: Optional[str],
-    project_name: Optional[str],
-    site_name: Optional[str],
+    module: str | None,
+    project_name: str | None,
+    site_name: str | None,
     docs_dir: Path,
     nav_file: Path,
-    template: Optional[Path],
+    template: Path | None,
     mkdocs_yml: Path,
     out_dir: Path,
 ) -> None: ...
-
 def serve(
     mcp: bool,
     mkdocs: bool,
-    module: Optional[str],
+    module: str | None,
     mkdocs_yml: Path,
     out_dir: Path,
 ) -> None: ...
-
 def tree(
     module: str,
-    project_name: Optional[str],
+    project_name: str | None,
 ) -> None: ...
-
 def _print_object(obj: Any, indent: str) -> None: ...

docforge/cli/main.py

@@ -22,4 +22,4 @@ def main() -> None:
 
 
 if __name__ == "__main__":
-    main()
+    main()

docforge/cli/mcp_utils.py

@@ -5,7 +5,9 @@ Utilities for working with MCP in the doc-forge CLI.
 """
 
 from pathlib import Path
+
 import click
+
 from docforge.loaders import GriffeLoader, discover_module_paths
 from docforge.renderers import MCPRenderer
 from docforge.servers import MCPServer

docforge/cli/mcp_utils.pyi

@@ -1,4 +1,6 @@
 from pathlib import Path
 
-def generate_resources(module: str, project_name: str | None, out_dir: Path) -> None: ...
+def generate_resources(
+    module: str, project_name: str | None, out_dir: Path
+) -> None: ...
 def serve(module: str, mcp_root: Path) -> None: ...

docforge/cli/mkdocs_utils.py

@@ -4,13 +4,15 @@
 Utilities for working with MkDocs in the doc-forge CLI.
 """
 
-from pathlib import Path
 from importlib import resources
+from pathlib import Path
+
 import click
 import yaml
+
 from docforge.loaders import GriffeLoader, discover_module_paths
+from docforge.nav import MkDocsNavEmitter, load_nav_spec, resolve_nav
 from docforge.renderers import MkDocsRenderer
-from docforge.nav import load_nav_spec, resolve_nav, MkDocsNavEmitter
 
 
 def generate_sources(
@@ -138,8 +140,8 @@ def build(mkdocs_yml: Path) -> None:
     if not mkdocs_yml.exists():
         raise click.ClickException(f"mkdocs.yml not found: {mkdocs_yml}")
 
-    from mkdocs.config import load_config
     from mkdocs.commands.build import build as mkdocs_build
+    from mkdocs.config import load_config
 
     mkdocs_build(load_config(str(mkdocs_yml)))
 
@@ -163,4 +165,5 @@ def serve(mkdocs_yml: Path) -> None:
         raise click.ClickException(f"mkdocs.yml not found: {mkdocs_yml}")
 
     from mkdocs.commands.serve import serve as mkdocs_serve
+
     mkdocs_serve(config_file=str(mkdocs_yml))

docforge/cli/mkdocs_utils.pyi

@@ -6,6 +6,8 @@ def generate_sources(
     project_name: str | None = None,
     module_is_source: bool | None = None,
 ) -> None: ...
-def generate_config(docs_dir: Path, nav_file: Path, template: Path | None, out: Path, site_name: str) -> None: ...
+def generate_config(
+    docs_dir: Path, nav_file: Path, template: Path | None, out: Path, site_name: str
+) -> None: ...
 def build(mkdocs_yml: Path) -> None: ...
 def serve(mkdocs_yml: Path) -> None: ...