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

updated doc strings

Browse Source
This commit is contained in:
Vishesh 'ironeagle' Bangotra
2026-03-07 15:44:02 +05:30
parent 73b15cc3ab
commit 17d39a3e88
21 changed files with 680 additions and 330 deletions
Download Patch File Download Diff File Expand all files Collapse all files

27
docforge/cli/__init__.py
View File

@@ -1,14 +1,27 @@
"""
# CLI Layer
Command line interface entry point for doc-forge.
The `docforge.cli` package provides the command-line interface for interacting
with doc-forge.
This module exposes the primary CLI entry function used by the
``doc-forge`` command. The actual command implementation resides in
``docforge.cli.main``, while this module provides a stable import path
for external tools and the package entry point configuration.
## Available Commands
The CLI is responsible for orchestrating documentation workflows such as
generating renderer sources, building documentation sites, exporting
machine-readable documentation bundles, and starting development or MCP
servers.
- **build**: Build documentation (MkDocs site or MCP resources).
- **serve**: Serve documentation (MkDocs or MCP).
- **tree**: Visualize the introspected project structure.
Typical usage
-------------
The CLI is normally invoked through the installed command:
doc-forge <command> [options]
Programmatic invocation is also possible:
from docforge.cli import main
main()
"""
from .main import main

88
docforge/cli/commands.py
View File

@@ -9,8 +9,10 @@ from docforge.cli import mcp_utils
@click.group()
def cli() -> None:
"""
doc-forge CLI: A tool for introspecting Python projects and generating
documentation.
Root command group for the doc-forge CLI.
Provides commands for building, serving, and inspecting
documentation generated from Python source code.
"""
pass
@@ -21,14 +23,12 @@ def cli() -> None:
@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")
# MkDocs specific
@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")
# MCP specific
@click.option("--out-dir", type=click.Path(path_type=Path), default=Path("mcp_docs"), help="MCP output directory")
def build(
mcp: bool,
@@ -44,25 +44,36 @@ def build(
out_dir: Path,
) -> None:
"""
Build documentation (MkDocs site or MCP resources).
Build documentation artifacts.
This command orchestrates the full build process:
1. Introspects the code (Griffe)
2. Renders sources (MkDocs Markdown or MCP JSON)
3. (MkDocs only) Generates config and runs the final site build.
This command performs the full documentation build pipeline:
1. Introspects the Python project using Griffe
2. Generates renderer-specific documentation sources
3. Optionally builds the final documentation output
Depending on the selected options, the build can target:
- MkDocs static documentation sites
- MCP structured documentation resources
Args:
mcp: Use the MCP documentation builder.
mkdocs: Use the MkDocs documentation builder.
module_is_source: Module is the source folder and to be treated as the root folder.
module: The dotted path of the module to the document.
mcp: Enable MCP documentation generation.
mkdocs: Enable MkDocs documentation generation.
module_is_source: Treat the specified module directory as the
project root.
module: Python module import path to document.
project_name: Optional override for the project name.
site_name: (MkDocs) The site display name. Defaults to module name.
docs_dir: (MkDocs) Target directory for Markdown sources.
nav_file: (MkDocs) Path to the docforge.nav.yml specification.
template: (MkDocs) Optional custom mkdocs.yml template.
mkdocs_yml: (MkDocs) Target path for the generated mkdocs.yml.
out_dir: (MCP) Target directory for MCP JSON resources.
site_name: Display name for the MkDocs site.
docs_dir: Directory where Markdown documentation sources
will be generated.
nav_file: Path to the navigation specification file.
template: Optional custom MkDocs configuration template.
mkdocs_yml: Output path for the generated MkDocs configuration.
out_dir: Output directory for generated MCP resources.
Raises:
click.UsageError: If required options are missing or conflicting.
"""
if not mcp and not mkdocs:
raise click.UsageError("Must specify either --mcp or --mkdocs")
@@ -111,14 +122,22 @@ def serve(
out_dir: Path,
) -> None:
"""
Serve documentation (MkDocs or MCP).
Serve generated documentation locally.
Depending on the selected mode, this command starts either:
- A MkDocs development server for browsing documentation
- An MCP server exposing structured documentation resources
Args:
mcp: Serve MCP resources via an MCP server.
mkdocs: Serve the MkDocs site using the built-in development server.
module: The dotted path of the module to serve.
mkdocs_yml: (MkDocs) Path to the mkdocs.yml configuration.
out_dir: (MCP) Path to the mcp_docs/ directory.
mcp: Serve documentation using the MCP server.
mkdocs: Serve the MkDocs development site.
module: Python module import path to serve via MCP.
mkdocs_yml: Path to the MkDocs configuration file.
out_dir: Root directory containing MCP documentation resources.
Raises:
click.UsageError: If invalid or conflicting options are provided.
"""
if mcp and mkdocs:
raise click.UsageError("Cannot specify both --mcp and --mkdocs")
@@ -148,11 +167,15 @@ def tree(
project_name: Optional[str],
) -> None:
"""
Visualize the project structure in the terminal.
Display the documentation object tree for a module.
This command introspects the specified module and prints a
hierarchical representation of the discovered documentation
objects, including modules, classes, functions, and members.
Args:
module: The module import path to recursively introspect.
project_name: Optional override for the project name shown at the root.
module: Python module import path to introspect.
project_name: Optional name to display as the project root.
"""
loader = GriffeLoader()
project = loader.load_project([module], project_name)
@@ -167,11 +190,14 @@ def tree(
def _print_object(obj, indent: str) -> None:
"""
Recursive helper to print doc objects and their members to the console.
Recursively print a documentation object and its members.
This helper function traverses the documentation object graph
and prints each object with indentation to represent hierarchy.
Args:
obj: The DocObject instance to print.
indent: Current line indentation (e.g., '│ ').
obj: Documentation object to print.
indent: Current indentation prefix used for nested members.
"""
click.echo(f"{indent}├── {obj.name}")
for member in obj.get_all_members():

17
docforge/cli/main.py
View File

@@ -1,14 +1,23 @@
"""
Main entry point for the doc-forge CLI. This module delegates all command
execution to docforge.cli.commands.
Command-line entry point for the doc-forge CLI.
This module exposes the executable entry point that initializes the
Click command group defined in ``docforge.cli.commands``.
"""
from docforge.cli.commands import cli
def main() -> None:
"""
CLI Entry point. Boots the click application.
Run the doc-forge command-line interface.
This function initializes and executes the Click CLI application.
It is used as the console entry point when invoking ``doc-forge``
from the command line.
"""
cli()
if __name__ == "__main__":
main()
main()

32
docforge/cli/mcp_utils.py
View File

@@ -4,14 +4,22 @@ from docforge.loaders import GriffeLoader, discover_module_paths
from docforge.renderers import MCPRenderer
from docforge.servers import MCPServer
def generate_resources(module: str, project_name: str | None, out_dir: Path) -> None:
"""
Generate MCP-compatible documentation resources.
Generate MCP documentation resources from a Python module.
The function performs project introspection, builds the internal
documentation model, and renders MCP-compatible JSON resources
to the specified output directory.
Args:
module: The dotted path of the primary module to document.
project_name: Optional override for the project name.
out_dir: Directory where the MCP JSON resources and nav will be written.
module: Python module import path used as the entry point for
documentation generation.
project_name: Optional override for the project name used in
generated documentation metadata.
out_dir: Directory where MCP resources (index.json, nav.json,
and module data) will be written.
"""
loader = GriffeLoader()
discovered_paths = discover_module_paths(module)
@@ -20,13 +28,23 @@ def generate_resources(module: str, project_name: str | None, out_dir: Path) ->
renderer = MCPRenderer()
renderer.generate_sources(project, out_dir)
def serve(module: str, mcp_root: Path) -> None:
"""
Serve MCP documentation from a pre-built bundle.
Start an MCP server for a pre-generated documentation bundle.
The server exposes documentation resources such as project metadata,
navigation structure, and module documentation through MCP endpoints.
Args:
module: The dotted path of the primary module to serve.
mcp_root: Path to the directory containing index.json, nav.json, and modules/.
module: Python module import path used to identify the served
documentation instance.
mcp_root: Path to the directory containing the MCP documentation
bundle (index.json, nav.json, and modules/).
Raises:
click.ClickException: If the MCP documentation bundle is missing
required files or directories.
"""
if not mcp_root.exists():
raise click.ClickException(f"mcp_docs directory not found: {mcp_root}")

69
docforge/cli/mkdocs_utils.py
View File

@@ -6,6 +6,7 @@ from docforge.loaders import GriffeLoader, discover_module_paths
from docforge.renderers import MkDocsRenderer
from docforge.nav import load_nav_spec, resolve_nav, MkDocsNavEmitter
def generate_sources(
module: str,
docs_dir: Path,
@@ -13,13 +14,20 @@ def generate_sources(
module_is_source: bool | None = None,
) -> None:
"""
Generate Markdown source files for the specified module.
Generate MkDocs Markdown sources for a Python module.
This function introspects the specified module, builds the internal
documentation model, and renders Markdown documentation files for
use with MkDocs.
Args:
module: The dotted path of the primary module to document.
project_name: Optional override for the project name.
module: Python module import path used as the entry point for
documentation generation.
docs_dir: Directory where the generated Markdown files will be written.
module_is_source: Module is the source folder and to be treated as the root folder.
project_name: Optional override for the project name used in
documentation metadata.
module_is_source: If True, treat the specified module directory as
the project root rather than a nested module.
"""
loader = GriffeLoader()
discovered_paths = discover_module_paths(module)
@@ -38,16 +46,33 @@ def generate_sources(
module_is_source,
)
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:
"""
Generate an mkdocs.yml configuration file.
Generate an ``mkdocs.yml`` configuration file.
The configuration is created by combining a template configuration
with a navigation structure derived from the docforge navigation
specification.
Args:
docs_dir: Path to the directory containing documentation Markdown files.
nav_file: Path to the docforge.nav.yml specification.
template: Optional path to an mkdocs.yml template (overrides built-in).
out: Path where the final mkdocs.yml will be written.
site_name: The display name for the documentation site.
docs_dir: Directory containing generated documentation Markdown files.
nav_file: Path to the ``docforge.nav.yml`` navigation specification.
template: Optional path to a custom MkDocs configuration template.
If not provided, a built-in template will be used.
out: Destination path where the generated ``mkdocs.yml`` file
will be written.
site_name: Display name for the generated documentation site.
Raises:
click.FileError: If the navigation specification or template
file cannot be found.
"""
if not nav_file.exists():
raise click.FileError(str(nav_file), hint="Nav spec not found")
@@ -74,12 +99,19 @@ def generate_config(docs_dir: Path, nav_file: Path, template: Path | None, out:
out.write_text(yaml.safe_dump(data, sort_keys=False), encoding="utf-8")
def build(mkdocs_yml: Path) -> None:
"""
Build the documentation site using MkDocs.
Build the MkDocs documentation site.
This function loads the MkDocs configuration and runs the MkDocs
build command to generate the final static documentation site.
Args:
mkdocs_yml: Path to the mkdocs.yml configuration file.
mkdocs_yml: Path to the ``mkdocs.yml`` configuration file.
Raises:
click.ClickException: If the configuration file does not exist.
"""
if not mkdocs_yml.exists():
raise click.ClickException(f"mkdocs.yml not found: {mkdocs_yml}")
@@ -89,12 +121,19 @@ def build(mkdocs_yml: Path) -> None:
mkdocs_build(load_config(str(mkdocs_yml)))
def serve(mkdocs_yml: Path) -> None:
"""
Serve the documentation site with live-reload using MkDocs.
Start an MkDocs development server with live reload.
The server watches documentation files and automatically reloads
the site when changes are detected.
Args:
mkdocs_yml: Path to the mkdocs.yml configuration file.
mkdocs_yml: Path to the ``mkdocs.yml`` configuration file.
Raises:
click.ClickException: If the configuration file does not exist.
"""
if not mkdocs_yml.exists():
raise click.ClickException(f"mkdocs.yml not found: {mkdocs_yml}")