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

updated docs strings and added README.md

Browse Source
This commit is contained in:
Vishesh 'ironeagle' Bangotra
2026-03-08 17:59:55 +05:30
parent e8e16f3996
commit 8253c25928
37 changed files with 1091 additions and 834 deletions
Download Patch File Download Diff File Expand all files Collapse all files

17
docforge/cli/__init__.py
View File

@@ -1,9 +1,11 @@
"""
# Summary
Command line interface entry point for 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
`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.
The CLI is responsible for orchestrating documentation workflows such as
@@ -13,17 +15,22 @@ servers.
---
Typical usage
-------------
# Typical usage
The CLI is normally invoked through the installed command:
doc-forge <command> [options]
```bash
doc-forge <command> [options]
```
Programmatic invocation is also possible:
Example:
```python
from docforge.cli import main
main()
```
---
"""

92
docforge/cli/commands.py
View File

@@ -1,3 +1,11 @@
"""
# Summary
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
@@ -58,22 +66,42 @@ def build(
- MCP structured documentation resources
Args:
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: 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.
mcp (bool):
Enable MCP documentation generation.
mkdocs (bool):
Enable MkDocs documentation generation.
module_is_source (bool):
Treat the specified module directory as the project root.
module (Optional[str]):
Python module import path to document.
project_name (Optional[str]):
Optional override for the project name.
site_name (Optional[str]):
Display name for the MkDocs site.
docs_dir (Path):
Directory where Markdown documentation sources will be generated.
nav_file (Path):
Path to the navigation specification file.
template (Optional[Path]):
Optional custom MkDocs configuration template.
mkdocs_yml (Path):
Output path for the generated MkDocs configuration.
out_dir (Path):
Output directory for generated MCP resources.
Raises:
click.UsageError: If required options are missing or conflicting.
click.UsageError:
If required options are missing or conflicting.
"""
if not mcp and not mkdocs:
raise click.UsageError("Must specify either --mcp or --mkdocs")
@@ -130,14 +158,24 @@ def serve(
- An MCP server exposing structured documentation resources
Args:
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.
mcp (bool):
Serve documentation using the MCP server.
mkdocs (bool):
Serve the MkDocs development site.
module (Optional[str]):
Python module import path to serve via MCP.
mkdocs_yml (Path):
Path to the MkDocs configuration file.
out_dir (Path):
Root directory containing MCP documentation resources.
Raises:
click.UsageError: If invalid or conflicting options are provided.
click.UsageError:
If invalid or conflicting options are provided.
"""
if mcp and mkdocs:
raise click.UsageError("Cannot specify both --mcp and --mkdocs")
@@ -174,8 +212,11 @@ def tree(
objects, including modules, classes, functions, and members.
Args:
module: Python module import path to introspect.
project_name: Optional name to display as the project root.
module (str):
Python module import path to introspect.
project_name (Optional[str]):
Optional name to display as the project root.
"""
loader = GriffeLoader()
project = loader.load_project([module], project_name)
@@ -196,8 +237,11 @@ def _print_object(obj, indent: str) -> None:
and prints each object with indentation to represent hierarchy.
Args:
obj: Documentation object to print.
indent: Current indentation prefix used for nested members.
obj:
Documentation object to print.
indent (str):
Current indentation prefix used for nested members.
"""
click.echo(f"{indent}├── {obj.name}")
for member in obj.get_all_members():

6
docforge/cli/main.py
View File

@@ -1,8 +1,10 @@
"""
# Summary
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``.
Click command group defined in `docforge.cli.commands`.
"""
from docforge.cli.commands import cli
@@ -13,7 +15,7 @@ def main() -> None:
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``
It is used as the console entry point when invoking `doc-forge`
from the command line.
"""
cli()

32
docforge/cli/mcp_utils.py
View File

@@ -1,3 +1,9 @@
"""
# Summary
Utilities for working with MCP in the doc-forge CLI.
"""
from pathlib import Path
import click
from docforge.loaders import GriffeLoader, discover_module_paths
@@ -14,12 +20,17 @@ def generate_resources(module: str, project_name: str | None, out_dir: Path) ->
to the specified output directory.
Args:
module: Python module import path used as the entry point for
module (str):
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.
project_name (Optional[str]):
Optional override for the project name used in generated
documentation metadata.
out_dir (Path):
Directory where MCP resources (index.json, nav.json, and module data)
will be written.
"""
loader = GriffeLoader()
discovered_paths = discover_module_paths(module)
@@ -37,14 +48,17 @@ def serve(module: str, mcp_root: Path) -> None:
navigation structure, and module documentation through MCP endpoints.
Args:
module: Python module import path used to identify the served
module (str):
Python module import path used to identify the served
documentation instance.
mcp_root: Path to the directory containing the MCP documentation
mcp_root (Path):
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.
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}")

64
docforge/cli/mkdocs_utils.py
View File

@@ -1,3 +1,9 @@
"""
# Summary
Utilities for working with MkDocs in the doc-forge CLI.
"""
from pathlib import Path
from importlib import resources
import click
@@ -21,13 +27,19 @@ def generate_sources(
use with MkDocs.
Args:
module: Python module import path used as the entry point for
module (str):
Python module import path used as the entry point for
documentation generation.
docs_dir: Directory where the generated Markdown files will be written.
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.
docs_dir (Path):
Directory where the generated Markdown files will be written.
project_name (Optional[str]):
Optional override for the project name used in documentation metadata.
module_is_source (Optional[bool]):
If True, treat the specified module directory as the project root
rather than a nested module.
"""
loader = GriffeLoader()
discovered_paths = discover_module_paths(module)
@@ -55,24 +67,32 @@ def generate_config(
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: 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.
docs_dir (Path):
Directory containing generated documentation Markdown files.
nav_file (Path):
Path to the `docforge.nav.yml` navigation specification.
template (Optional[Path]):
Optional path to a custom MkDocs configuration template. If not
provided, a built-in template will be used.
out (Path):
Destination path where the generated `mkdocs.yml` file will be written.
site_name (str):
Display name for the generated documentation site.
Raises:
click.FileError: If the navigation specification or template
file cannot be found.
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")
@@ -108,10 +128,12 @@ def build(mkdocs_yml: Path) -> None:
build command to generate the final static documentation site.
Args:
mkdocs_yml: Path to the ``mkdocs.yml`` configuration file.
mkdocs_yml (Path):
Path to the `mkdocs.yml` configuration file.
Raises:
click.ClickException: If the configuration file does not exist.
click.ClickException:
If the configuration file does not exist.
"""
if not mkdocs_yml.exists():
raise click.ClickException(f"mkdocs.yml not found: {mkdocs_yml}")
@@ -130,10 +152,12 @@ def serve(mkdocs_yml: Path) -> None:
the site when changes are detected.
Args:
mkdocs_yml: Path to the ``mkdocs.yml`` configuration file.
mkdocs_yml (Path):
Path to the `mkdocs.yml` configuration file.
Raises:
click.ClickException: If the configuration file does not exist.
click.ClickException:
If the configuration file does not exist.
"""
if not mkdocs_yml.exists():
raise click.ClickException(f"mkdocs.yml not found: {mkdocs_yml}")