From 86a4f8f41a1977a999735617ae5ea0de2224df7b Mon Sep 17 00:00:00 2001 From: Vishesh 'ironeagle' Bangotra Date: Tue, 20 Jan 2026 18:00:28 +0530 Subject: [PATCH] added ADS --- ADS.llm.md | 327 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 327 insertions(+) create mode 100644 ADS.llm.md diff --git a/ADS.llm.md b/ADS.llm.md new file mode 100644 index 0000000..112492c --- /dev/null +++ b/ADS.llm.md @@ -0,0 +1,327 @@ +# doc-forge — Architecture & Design Specification + +**doc-forge** is a renderer-agnostic Python documentation compiler. It converts Python source code and docstrings into a structured, semantic documentation model and then emits multiple downstream representations, including: + +* Human-facing documentation sites (MkDocs, Sphinx) +* Machine-facing documentation bundles (MCP JSON) +* Live documentation APIs (MCP servers) + +This document is the **authoritative design and codebase specification** for the library. It is written to be both **LLM-friendly** and **developer-facing**, and should be treated as the canonical reference for implementation decisions. + +--- + +## 1. Design Goals + +1. **Single Source of Truth** + Python source code and docstrings are the only authoritative input. + +2. **Renderer Agnosticism** + MkDocs, Sphinx, MCP, or future renderers must not influence the core model. + +3. **Deterministic Output** + Given the same codebase, outputs must be reproducible. + +4. **AI-Native Documentation** + Documentation must be structured, queryable, and machine-consumable. + +5. **Library-First, CLI-Second** + All functionality must be accessible as a Python API. The CLI is a thin wrapper. + +--- + +## 2. Core Mental Model + +### Fundamental Abstraction + +> **The atomic unit of documentation is a Python import path** + +Examples: + +* `mail_intake` +* `mail_intake.config` +* `mail_intake.adapters.base` + +Files, Markdown, HTML, and JSON are *representations*, not documentation units. + +--- + +## 3. High-Level Architecture + +``` +Python Source Code + ↓ +Introspection Layer (Griffe) + ↓ +Documentation Model (doc-forge core) + ↓ +Renderer / Exporter Layer + ├── MkDocs + ├── Sphinx + ├── MCP (static JSON) + └── MCP Server (live) +``` + +Only the **Documentation Model** is shared across all outputs. + +--- + +## 4. Package Layout (Proposed) + +``` +docforge/ +├── __init__.py +├── model/ +│ ├── project.py +│ ├── module.py +│ ├── object.py +│ └── nav.py +├── loader/ +│ └── griffe_loader.py +├── renderers/ +│ ├── base.py +│ ├── mkdocs.py +│ └── sphinx.py +├── exporters/ +│ └── mcp.py +├── server/ +│ └── mcp_server.py +├── cli/ +│ └── main.py +└── utils/ +``` + +--- + +## 5. Documentation Model (Core) + +The documentation model is renderer-neutral and must not contain any MkDocs-, Sphinx-, or MCP-specific logic. + +### 5.1 Project + +```python +class Project: + name: str + version: str | None + modules: dict[str, Module] + nav: Navigation +``` + +--- + +### 5.2 Module + +```python +class Module: + path: str # import path + docstring: str | None + members: dict[str, DocObject] +``` + +--- + +### 5.3 DocObject + +Represents classes, functions, variables, etc. + +```python +class DocObject: + name: str + kind: str # class, function, attribute, module + path: str + signature: str | None + docstring: str | None + members: dict[str, DocObject] +``` + +Private members (`_name`) are excluded by default. + +--- + +### 5.4 Navigation + +```python +class Navigation: + entries: list[NavEntry] + +class NavEntry: + title: str + module: str +``` + +Navigation is derived, not authored. + +--- + +## 6. Introspection Layer + +### 6.1 Griffe Loader + +Griffe is the **only supported introspection backend**. + +Responsibilities: + +* Load modules by import path +* Resolve docstrings, signatures, and members +* Tolerate alias resolution failures + +Output: fully populated `Project` and `Module` objects. + +--- + +## 7. Renderer Interface + +Renderers consume the documentation model and emit renderer-specific source trees. + +```python +class DocRenderer(Protocol): + name: str + + def generate_sources(self, project: Project, out_dir: Path) -> None: + """Generate renderer-specific source files.""" + + def build(self, config: RendererConfig) -> None: + """Build final artifacts (HTML, site, etc.).""" + + def serve(self, config: RendererConfig) -> None: + """Serve documentation locally (optional).""" +``` + +--- + +## 8. MkDocs Renderer + +### Source Generation + +* Emits `.md` files +* One file per module +* Uses `mkdocstrings` directives exclusively + +```md +# Config + +::: mail_intake.config +``` + +### Build + +* Uses `mkdocs.commands.build` + +### Serve + +* Uses `mkdocs.commands.serve` + +MkDocs-specific configuration lives outside the core model. + +--- + +## 9. Sphinx Renderer + +### Source Generation + +* Emits `.rst` files +* Uses `autodoc` directives + +```rst +mail_intake.config +================== + +.. automodule:: mail_intake.config + :members: + :undoc-members: +``` + +### Build + +* Uses `sphinx.application.Sphinx` directly + +### Serve + +* Optional (static build is sufficient) + +--- + +## 10. MCP Exporter (Static) + +The MCP exporter bypasses renderers entirely. + +### Output Structure + +``` +mcp/ +├── index.json +├── nav.json +└── modules/ + └── package.module.json +``` + +### Design Principles + +* Alias-safe +* Deterministic +* Fully self-contained +* No Markdown, HTML, or templates + +--- + +## 11. MCP Server (Live) + +The MCP server exposes documentation as queryable resources. + +### Resources + +* `docs://index` +* `docs://nav` +* `docs://module/{module}` + +### Characteristics + +* Read-only +* Stateless +* Backed by MCP JSON bundle + +--- + +## 12. CLI Design + +The CLI is a thin orchestration layer. + +```bash +doc-forge generate --renderer mkdocs +doc-forge generate --renderer sphinx + +doc-forge build --renderer mkdocs +doc-forge serve --renderer mkdocs + +doc-forge export mcp +``` + +Renderer choice never affects the core model. + +--- + +## 13. Explicit Non-Goals + +* Markdown authoring +* Theme design +* Runtime code execution +* Code formatting or linting + +--- + +## 14. Invariants (Must Never Break) + +1. Import paths are canonical identifiers +2. Core model contains no renderer logic +3. MCP does not depend on MkDocs or Sphinx +4. Renderers do not introspect Python directly +5. All outputs trace back to the same model + +--- + +## 15. One-Line Definition + +> **doc-forge is a documentation compiler that turns Python code into structured knowledge and emits it through multiple human and machine interfaces.** + +--- + +*End of specification.*