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

cli-cleanup #1

Merged
aetos merged 6 commits from cli-cleanup into main 2026-01-21 13:23:33 +00:00
Conversation 0 Commits 6 Files Changed 38 +2206 -1524
aetos commented 2026-01-21 13:20:39 +00:00
Owner
Copy Link

Refactor: Modular CLI Structure, Type Synchronization, and Documentation Audit

This PR overhauls the doc-forge CLI for better maintainability, synchronizes type stubs across the package, and completes a comprehensive docstring audit to support high-quality documentation generation.

Key Changes

1. CLI Consolidation and Restructuring

  • Logical Decoupling: Moved orchestration logic out of command definitions and into specialized utility modules (docforge.cli.mkdocs_utils and docforge.cli.mcp_utils).
  • Command Simplification: Replaced numerous specialized commands (generate, generate-mcp, mkdocs, serve-mcp) with two high-level entry points:
    • doc-forge build: Handles introspection, source generation, and final site building for both MkDocs and MCP.
    • doc-forge serve: Launches development servers for both formats.
  • Modular Entry points: Refactored main.py into a thin wrapper, delegating to commands.py for CLI structure.

2. Type System Alignment (.pyi files)

  • Completed work to ensure every .py file has a corresponding .pyi stub that matches its signature.
  • Added missing stubs for the servers sub-package and new CLI utility modules.
  • Synchronized all exports in __init__.pyi files.

3. Documentation Audit (Human and LLM focused)

  • Performed a full sweep for missing or insufficient docstrings.
  • Populated all public (and significant internal) functions with Google-style Args and Returns blocks.
  • Improved documentation for MCP-specific components to ensure effective interaction when the library is used as an MCP server for LLMs.

4. Test Suite Refactoring

  • Restructured tests/ to match the new modular organization, creating dedicated tests/mkdocs/ and tests/mcp/ directories.
  • Updated test cases to verify the new integrated build and serve workflows.

How to Verify

Run the updated test suite:

pytest tests

Manual check of the new CLI:

# Build MkDocs
doc-forge build --mkdocs --module docforge --site-name "New Docs"

# Serve MCP
doc-forge serve --mcp

Impact

  • Developers: Cleaner separation of concerns in the CLI layer makes it easier to add new renderers or orchestration steps.
  • Users: A more intuitive command structure with fewer top-level commands to remember.
  • Tooling: Full .pyi coverage provides better IDE completion and stricter type-checking for downstream consumers.
# Refactor: Modular CLI Structure, Type Synchronization, and Documentation Audit This PR overhauls the `doc-forge` CLI for better maintainability, synchronizes type stubs across the package, and completes a comprehensive docstring audit to support high-quality documentation generation. ### Key Changes #### 1. CLI Consolidation and Restructuring * **Logical Decoupling**: Moved orchestration logic out of command definitions and into specialized utility modules (`docforge.cli.mkdocs_utils` and `docforge.cli.mcp_utils`). * **Command Simplification**: Replaced numerous specialized commands (`generate`, `generate-mcp`, `mkdocs`, `serve-mcp`) with two high-level entry points: * `doc-forge build`: Handles introspection, source generation, and final site building for both MkDocs and MCP. * `doc-forge serve`: Launches development servers for both formats. * **Modular Entry points**: Refactored `main.py` into a thin wrapper, delegating to `commands.py` for CLI structure. #### 2. Type System Alignment (.pyi files) * Completed work to ensure every `.py` file has a corresponding `.pyi` stub that matches its signature. * Added missing stubs for the `servers` sub-package and new CLI utility modules. * Synchronized all exports in `__init__.pyi` files. #### 3. Documentation Audit (Human and LLM focused) * Performed a full sweep for missing or insufficient docstrings. * Populated all public (and significant internal) functions with Google-style `Args` and `Returns` blocks. * Improved documentation for MCP-specific components to ensure effective interaction when the library is used as an MCP server for LLMs. #### 4. Test Suite Refactoring * Restructured `tests/` to match the new modular organization, creating dedicated `tests/mkdocs/` and `tests/mcp/` directories. * Updated test cases to verify the new integrated `build` and `serve` workflows. ### How to Verify Run the updated test suite: ```powershell pytest tests ``` Manual check of the new CLI: ```bash # Build MkDocs doc-forge build --mkdocs --module docforge --site-name "New Docs" # Serve MCP doc-forge serve --mcp ``` ### Impact * **Developers**: Cleaner separation of concerns in the CLI layer makes it easier to add new renderers or orchestration steps. * **Users**: A more intuitive command structure with fewer top-level commands to remember. * **Tooling**: Full `.pyi` coverage provides better IDE completion and stricter type-checking for downstream consumers.
aetos added 6 commits 2026-01-21 13:20:40 +00:00
refactor: restructure CLI and improve documentation/typing 03caf5ce4c 
- Consolidated CLI commands into [build](cci:1://file:///c:/Users/vishe/WorkSpace/code/aetos/doc-forge/docforge/cli/mkdocs/logic.py:48:0-58:46) and [serve](cci:1://file:///c:/Users/vishe/WorkSpace/code/aetos/doc-forge/docforge/cli/commands.py:70:0-92:32) using `--mkdocs` and `--mcp` flags.
- Separated CLI orchestration logic into [docforge/cli/mkdocs/logic.py](cci:7://file:///c:/Users/vishe/WorkSpace/code/aetos/doc-forge/docforge/cli/mkdocs/logic.py:0:0-0:0) and [docforge/cli/mcp/logic.py](cci:7://file:///c:/Users/vishe/WorkSpace/code/aetos/doc-forge/docforge/cli/mcp/logic.py:0:0-0:0).
- Moved command definitions to [docforge/cli/commands.py](cci:7://file:///c:/Users/vishe/WorkSpace/code/aetos/doc-forge/docforge/cli/commands.py:0:0-0:0), making [main.py](cci:7://file:///c:/Users/vishe/WorkSpace/code/aetos/doc-forge/docforge/cli/main.py:0:0-0:0) a thin entry point.
- Aligned [.pyi](cci:7://file:///c:/Users/vishe/WorkSpace/code/aetos/doc-forge/docforge/cli/main.pyi:0:0-0:0) type stubs with [.py](cci:7://file:///c:/Users/vishe/WorkSpace/code/aetos/doc-forge/tests/conftest.py:0:0-0:0) implementations across the package.
- Added missing docstrings to internal helper functions and core classes.
- Restructured tests into `tests/mkdocs/` and `tests/mcp/`.
- Updated navigation specification to reflect the new project structure.
site name correct position 8e97e571b7
refactored _logic to _utils and test cases fixes. site name is not mandatory now 711bef1dce
doc changes 9a066eb0af
added missing pyi files c82868d5a7
cli example changes bd294bea30
aetos merged commit 94c1818103 into main 2026-01-21 13:23:33 +00:00
aetos deleted branch cli-cleanup 2026-01-21 13:23:33 +00:00
aetos referenced this issue from a commit 2026-01-21 13:23:35 +00:00
cli-cleanup (#1)
Sign in to join this conversation.
Reviewers
No Reviewers
Labels
No items
No Label
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
aetos
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: aetos/doc-forge#1
No description provided.
Delete Branch "cli-cleanup"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?