refresh docs and mcp
This commit is contained in:
@@ -2,7 +2,7 @@
|
||||
"module": "docforge",
|
||||
"content": {
|
||||
"path": "docforge",
|
||||
"docstring": "# doc-forge\n\n`doc-forge` is a renderer-agnostic Python documentation compiler designed for\nspeed, flexibility, and beautiful output. It decouples the introspection of\nyour code from the rendering process, allowing you to generate documentation\nfor various platforms (starting with MkDocs) from a single internal models.\n\n## Available Commands\n\n- **build**: Build documentation (MkDocs site or MCP resources).\n- **serve**: Serve documentation (MkDocs or MCP).\n- **tree**: Visualize the introspected project structure.\n\n## Installation\n\nInstall using `pip` with the optional `mkdocs` dependencies for a complete setup:\n\n```bash\npip install doc-forge\n```\n\n## Quick Start\n\n1. **Build Documentation**:\n Introspect your package and generate documentation in one step:\n ```bash\n # Build MkDocs site\n doc-forge build --mkdocs --module my_package --site-name \"My Docs\"\n\n # Build MCP resources\n doc-forge build --mcp --module my_package\n ```\n\n2. **Define Navigation**:\n Create a `docforge.nav.yml` to organize your documentation:\n ```yaml\n home: my_package/index.md\n groups:\n Core API:\n - my_package/core/*.md\n Utilities:\n - my_package/utils.md\n ```\n\n3. **Preview**:\n ```bash\n # Serve MkDocs site\n doc-forge serve --mkdocs\n\n # Serve MCP documentation\n doc-forge serve --mcp\n ```\n\n## Project Structure\n\n- `docforge.loaders`: Introspects source code using static analysis (`griffe`).\n- `docforge.models`: The internal representation of your project, modules, and objects.\n- `docforge.renderers`: Converters that turn the models into physical files.\n- `docforge.nav`: Managers for logical-to-physical path mapping and navigation.",
|
||||
"docstring": "# doc-forge\n\n`doc-forge` is a renderer-agnostic Python documentation compiler designed for\nspeed, flexibility, and beautiful output. It decouples the introspection of\nyour code from the rendering process, allowing you to generate documentation\nfor various platforms (starting with MkDocs) from a single internal models.\n\n## Core Philosophy\n\n`doc-forge` operates on two fundamental principles:\n\n1. **The Atomic Unit is a Python Import Path**: Documentation is organized around the semantic structure of your code (e.g., `mypackage.utils`), not the filesystem.\n2. **The Documentation Compiler Paradigm**: We separate documentation into three distinct phases:\n - **Front-end (Introspection)**: Static analysis of source code and docstrings.\n - **Middle-end (Semantic Model)**: A renderer-neutral internal representation.\n - **Back-end (Renderers)**: Generation of human-facing (MkDocs) or machine-facing (MCP) outputs.\n\n## Documentation Design\n\n`doc-forge` is an \"AI-Native\" documentation compiler. To get the most out of it, design your docstrings with both humans and LLMs in mind:\n\n### For Humans (Readability & Structure)\n- **`__init__.py` as Landing Pages**: Use the docstring of your package's `__init__.py` as the home page. Include overviews, installation instructions, and high-level examples here.\n- **Single Source of Truth**: Keep all technical details in docstrings. This ensures your MkDocs/Sphinx sites stay in sync with the code.\n- **Semantic Hierarchy**: Use standard Markdown headers to structure complex module documentation.\n\n### For LLMs (AI-Native Knowledge)\n- **Model Context Protocol (MCP)**: `doc-forge` exports your docs as structured JSON. This allows AI agents to \"understand\" your API surface area without layout noise.\n- **Canonical Paths**: Use dotted import paths as primary identifiers. AI tools use these to link code usage to documentation.\n- **Type Annotations**: While not in docstrings, `doc-forge` (via Griffe) extracts signatures. Clean type hints dramatically improve an LLM's ability to generate correct code using your library.\n## Available Commands\n\n- **build**: Build documentation (MkDocs site or MCP resources).\n- **serve**: Serve documentation (MkDocs or MCP).\n- **tree**: Visualize the introspected project structure.\n\n## Installation\n\nInstall using `pip` with the optional `mkdocs` dependencies for a complete setup:\n\n```bash\npip install doc-forge\n```\n\n## Quick Start\n\n1. **Build Documentation**:\n Introspect your package and generate documentation in one step:\n ```bash\n # Build MkDocs site\n doc-forge build --mkdocs --module my_package --site-name \"My Docs\"\n\n # Build MCP resources\n doc-forge build --mcp --module my_package\n ```\n\n2. **Define Navigation**:\n Create a `docforge.nav.yml` to organize your documentation:\n ```yaml\n home: my_package/index.md\n groups:\n Core API:\n - my_package/core/*.md\n Utilities:\n - my_package/utils.md\n ```\n\n3. **Preview**:\n ```bash\n # Serve MkDocs site\n doc-forge serve --mkdocs\n\n # Serve MCP documentation\n doc-forge serve --mcp\n ```\n\n## Project Structure\n\n- `docforge.loaders`: Introspects source code using static analysis (`griffe`).\n- `docforge.models`: The internal representation of your project, modules, and objects.\n- `docforge.renderers`: Converters that turn the models into physical files.\n- `docforge.nav`: Managers for logical-to-physical path mapping and navigation.",
|
||||
"objects": {
|
||||
"GriffeLoader": {
|
||||
"name": "GriffeLoader",
|
||||
@@ -53,7 +53,7 @@
|
||||
"kind": "function",
|
||||
"path": "docforge.MkDocsRenderer.generate_sources",
|
||||
"signature": "<bound method Alias.signature of Alias('generate_sources', 'docforge.renderers.mkdocs_renderer.MkDocsRenderer.generate_sources')>",
|
||||
"docstring": "Produce a set of Markdown files in the output directory based on the\nprovided Project models.\n\nArgs:\n project: The project models to render.\n out_dir: Target directory for documentation files."
|
||||
"docstring": "Produce a set of Markdown files in the output directory based on the\nprovided Project models.\n\nArgs:\n project: The project models to render.\n out_dir: Target directory for documentation files.\n module_is_source: Module is the source folder and to be treated as the root folder."
|
||||
}
|
||||
}
|
||||
},
|
||||
@@ -275,7 +275,7 @@
|
||||
"kind": "function",
|
||||
"path": "docforge.cli.commands.mkdocs_utils.MkDocsRenderer.generate_sources",
|
||||
"signature": "<bound method Alias.signature of Alias('generate_sources', 'docforge.renderers.mkdocs_renderer.MkDocsRenderer.generate_sources')>",
|
||||
"docstring": "Produce a set of Markdown files in the output directory based on the\nprovided Project models.\n\nArgs:\n project: The project models to render.\n out_dir: Target directory for documentation files."
|
||||
"docstring": "Produce a set of Markdown files in the output directory based on the\nprovided Project models.\n\nArgs:\n project: The project models to render.\n out_dir: Target directory for documentation files.\n module_is_source: Module is the source folder and to be treated as the root folder."
|
||||
}
|
||||
}
|
||||
},
|
||||
@@ -314,7 +314,7 @@
|
||||
"kind": "function",
|
||||
"path": "docforge.cli.commands.mkdocs_utils.generate_sources",
|
||||
"signature": "<bound method Alias.signature of Alias('generate_sources', 'docforge.cli.mkdocs_utils.generate_sources')>",
|
||||
"docstring": "Generate Markdown source files for the specified module.\n\nArgs:\n module: The dotted path of the primary module to document.\n project_name: Optional override for the project name.\n docs_dir: Directory where the generated Markdown files will be written."
|
||||
"docstring": "Generate Markdown source files for the specified module.\n\nArgs:\n module: The dotted path of the primary module to document.\n project_name: Optional override for the project name.\n docs_dir: Directory where the generated Markdown files will be written.\n module_is_source: Module is the source folder and to be treated as the root folder."
|
||||
},
|
||||
"generate_config": {
|
||||
"name": "generate_config",
|
||||
@@ -455,7 +455,7 @@
|
||||
"kind": "function",
|
||||
"path": "docforge.cli.commands.mcp_utils.serve",
|
||||
"signature": "<bound method Alias.signature of Alias('serve', 'docforge.cli.mcp_utils.serve')>",
|
||||
"docstring": "Serve MCP documentation from a pre-built bundle.\n\nArgs:\n mcp_root: Path to the directory containing index.json, nav.json, and modules/."
|
||||
"docstring": "Serve MCP documentation from a pre-built bundle.\n\nArgs:\n module: The dotted path of the primary module to serve.\n mcp_root: Path to the directory containing index.json, nav.json, and modules/."
|
||||
}
|
||||
}
|
||||
},
|
||||
@@ -470,22 +470,22 @@
|
||||
"name": "build",
|
||||
"kind": "function",
|
||||
"path": "docforge.cli.commands.build",
|
||||
"signature": "<bound method Function.signature of Function('build', 18, 89)>",
|
||||
"docstring": "Build documentation (MkDocs site or MCP resources).\n\nThis command orchestrates the full build process:\n1. Introspects the code (Griffe)\n2. Renders sources (MkDocs Markdown or MCP JSON)\n3. (MkDocs only) Generates config and runs the final site build.\n\nArgs:\n mcp: Use the MCP documentation builder.\n mkdocs: Use the MkDocs documentation builder.\n module: The dotted path of the module to document.\n project_name: Optional override for the project name.\n site_name: (MkDocs) The site display name. Defaults to module name.\n docs_dir: (MkDocs) Target directory for Markdown sources.\n nav_file: (MkDocs) Path to the docforge.nav.yml specification.\n template: (MkDocs) Optional custom mkdocs.yml template.\n mkdocs_yml: (MkDocs) Target path for the generated mkdocs.yml.\n out_dir: (MCP) Target directory for MCP JSON resources."
|
||||
"signature": "<bound method Function.signature of Function('build', 18, 97)>",
|
||||
"docstring": "Build documentation (MkDocs site or MCP resources).\n\nThis command orchestrates the full build process:\n1. Introspects the code (Griffe)\n2. Renders sources (MkDocs Markdown or MCP JSON)\n3. (MkDocs only) Generates config and runs the final site build.\n\nArgs:\n mcp: Use the MCP documentation builder.\n mkdocs: Use the MkDocs documentation builder.\n module_is_source: Module is the source folder and to be treated as the root folder.\n module: The dotted path of the module to the document.\n project_name: Optional override for the project name.\n site_name: (MkDocs) The site display name. Defaults to module name.\n docs_dir: (MkDocs) Target directory for Markdown sources.\n nav_file: (MkDocs) Path to the docforge.nav.yml specification.\n template: (MkDocs) Optional custom mkdocs.yml template.\n mkdocs_yml: (MkDocs) Target path for the generated mkdocs.yml.\n out_dir: (MCP) Target directory for MCP JSON resources."
|
||||
},
|
||||
"serve": {
|
||||
"name": "serve",
|
||||
"kind": "function",
|
||||
"path": "docforge.cli.commands.serve",
|
||||
"signature": "<bound method Function.signature of Function('serve', 92, 120)>",
|
||||
"docstring": "Serve documentation (MkDocs or MCP).\n\nArgs:\n mcp: Serve MCP resources via an MCP server.\n mkdocs: Serve the MkDocs site using the built-in development server.\n mkdocs_yml: (MkDocs) Path to the mkdocs.yml configuration.\n out_dir: (MCP) Path to the mcp_docs/ directory."
|
||||
"signature": "<bound method Function.signature of Function('serve', 100, 133)>",
|
||||
"docstring": "Serve documentation (MkDocs or MCP).\n\nArgs:\n mcp: Serve MCP resources via an MCP server.\n mkdocs: Serve the MkDocs site using the built-in development server.\n module: The dotted path of the module to serve.\n mkdocs_yml: (MkDocs) Path to the mkdocs.yml configuration.\n out_dir: (MCP) Path to the mcp_docs/ directory."
|
||||
},
|
||||
"tree": {
|
||||
"name": "tree",
|
||||
"kind": "function",
|
||||
"path": "docforge.cli.commands.tree",
|
||||
"signature": "<bound method Function.signature of Function('tree', 123, 153)>",
|
||||
"docstring": "Visualize the project structure in the terminal.\n\nArgs:\n modules: List of module import paths to recursively introspect.\n project_name: Optional override for the project name shown at the root."
|
||||
"signature": "<bound method Function.signature of Function('tree', 136, 165)>",
|
||||
"docstring": "Visualize the project structure in the terminal.\n\nArgs:\n module: The module import path to recursively introspect.\n project_name: Optional override for the project name shown at the root."
|
||||
},
|
||||
"Group": {
|
||||
"name": "Group",
|
||||
@@ -618,8 +618,8 @@
|
||||
"name": "serve",
|
||||
"kind": "function",
|
||||
"path": "docforge.cli.mcp_utils.serve",
|
||||
"signature": "<bound method Function.signature of Function('serve', 23, 47)>",
|
||||
"docstring": "Serve MCP documentation from a pre-built bundle.\n\nArgs:\n mcp_root: Path to the directory containing index.json, nav.json, and modules/."
|
||||
"signature": "<bound method Function.signature of Function('serve', 23, 48)>",
|
||||
"docstring": "Serve MCP documentation from a pre-built bundle.\n\nArgs:\n module: The dotted path of the primary module to serve.\n mcp_root: Path to the directory containing index.json, nav.json, and modules/."
|
||||
}
|
||||
}
|
||||
},
|
||||
@@ -707,7 +707,7 @@
|
||||
"kind": "function",
|
||||
"path": "docforge.cli.mkdocs_utils.MkDocsRenderer.generate_sources",
|
||||
"signature": "<bound method Alias.signature of Alias('generate_sources', 'docforge.renderers.mkdocs_renderer.MkDocsRenderer.generate_sources')>",
|
||||
"docstring": "Produce a set of Markdown files in the output directory based on the\nprovided Project models.\n\nArgs:\n project: The project models to render.\n out_dir: Target directory for documentation files."
|
||||
"docstring": "Produce a set of Markdown files in the output directory based on the\nprovided Project models.\n\nArgs:\n project: The project models to render.\n out_dir: Target directory for documentation files.\n module_is_source: Module is the source folder and to be treated as the root folder."
|
||||
}
|
||||
}
|
||||
},
|
||||
@@ -745,28 +745,28 @@
|
||||
"name": "generate_sources",
|
||||
"kind": "function",
|
||||
"path": "docforge.cli.mkdocs_utils.generate_sources",
|
||||
"signature": "<bound method Function.signature of Function('generate_sources', 9, 23)>",
|
||||
"docstring": "Generate Markdown source files for the specified module.\n\nArgs:\n module: The dotted path of the primary module to document.\n project_name: Optional override for the project name.\n docs_dir: Directory where the generated Markdown files will be written."
|
||||
"signature": "<bound method Function.signature of Function('generate_sources', 9, 33)>",
|
||||
"docstring": "Generate Markdown source files for the specified module.\n\nArgs:\n module: The dotted path of the primary module to document.\n project_name: Optional override for the project name.\n docs_dir: Directory where the generated Markdown files will be written.\n module_is_source: Module is the source folder and to be treated as the root folder."
|
||||
},
|
||||
"generate_config": {
|
||||
"name": "generate_config",
|
||||
"kind": "function",
|
||||
"path": "docforge.cli.mkdocs_utils.generate_config",
|
||||
"signature": "<bound method Function.signature of Function('generate_config', 25, 59)>",
|
||||
"signature": "<bound method Function.signature of Function('generate_config', 35, 69)>",
|
||||
"docstring": "Generate an mkdocs.yml configuration file.\n\nArgs:\n docs_dir: Path to the directory containing documentation Markdown files.\n nav_file: Path to the docforge.nav.yml specification.\n template: Optional path to an mkdocs.yml template (overrides built-in).\n out: Path where the final mkdocs.yml will be written.\n site_name: The display name for the documentation site."
|
||||
},
|
||||
"build": {
|
||||
"name": "build",
|
||||
"kind": "function",
|
||||
"path": "docforge.cli.mkdocs_utils.build",
|
||||
"signature": "<bound method Function.signature of Function('build', 61, 74)>",
|
||||
"signature": "<bound method Function.signature of Function('build', 71, 84)>",
|
||||
"docstring": "Build the documentation site using MkDocs.\n\nArgs:\n mkdocs_yml: Path to the mkdocs.yml configuration file."
|
||||
},
|
||||
"serve": {
|
||||
"name": "serve",
|
||||
"kind": "function",
|
||||
"path": "docforge.cli.mkdocs_utils.serve",
|
||||
"signature": "<bound method Function.signature of Function('serve', 76, 87)>",
|
||||
"signature": "<bound method Function.signature of Function('serve', 86, 97)>",
|
||||
"docstring": "Serve the documentation site with live-reload using MkDocs.\n\nArgs:\n mkdocs_yml: Path to the mkdocs.yml configuration file."
|
||||
}
|
||||
}
|
||||
@@ -2079,7 +2079,7 @@
|
||||
"kind": "function",
|
||||
"path": "docforge.renderers.MkDocsRenderer.generate_sources",
|
||||
"signature": "<bound method Alias.signature of Alias('generate_sources', 'docforge.renderers.mkdocs_renderer.MkDocsRenderer.generate_sources')>",
|
||||
"docstring": "Produce a set of Markdown files in the output directory based on the\nprovided Project models.\n\nArgs:\n project: The project models to render.\n out_dir: Target directory for documentation files."
|
||||
"docstring": "Produce a set of Markdown files in the output directory based on the\nprovided Project models.\n\nArgs:\n project: The project models to render.\n out_dir: Target directory for documentation files.\n module_is_source: Module is the source folder and to be treated as the root folder."
|
||||
}
|
||||
}
|
||||
},
|
||||
@@ -2465,7 +2465,7 @@
|
||||
"kind": "module",
|
||||
"path": "docforge.renderers.mkdocs_renderer",
|
||||
"signature": null,
|
||||
"docstring": "This module implements the MkDocsRenderer, which generates Markdown source files\ncompatible with the MkDocs 'material' theme and 'mkdocstrings' extension.",
|
||||
"docstring": "MkDocsRenderer\n\nGenerates Markdown source files compatible with MkDocs Material\nand mkdocstrings, ensuring:\n\n- Root index.md always exists\n- Parent package indexes are created automatically\n- Child modules are linked in parent index files",
|
||||
"members": {
|
||||
"Path": {
|
||||
"name": "Path",
|
||||
@@ -2525,36 +2525,6 @@
|
||||
}
|
||||
}
|
||||
},
|
||||
"MkDocsRenderer": {
|
||||
"name": "MkDocsRenderer",
|
||||
"kind": "class",
|
||||
"path": "docforge.renderers.mkdocs_renderer.MkDocsRenderer",
|
||||
"signature": "<bound method Class.signature of Class('MkDocsRenderer', 11, 91)>",
|
||||
"docstring": "Renderer that generates Markdown source files formatted for the MkDocs\n'mkdocstrings' plugin.",
|
||||
"members": {
|
||||
"name": {
|
||||
"name": "name",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.renderers.mkdocs_renderer.MkDocsRenderer.name",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"generate_sources": {
|
||||
"name": "generate_sources",
|
||||
"kind": "function",
|
||||
"path": "docforge.renderers.mkdocs_renderer.MkDocsRenderer.generate_sources",
|
||||
"signature": "<bound method Function.signature of Function('generate_sources', 19, 38)>",
|
||||
"docstring": "Produce a set of Markdown files in the output directory based on the\nprovided Project models.\n\nArgs:\n project: The project models to render.\n out_dir: Target directory for documentation files."
|
||||
}
|
||||
}
|
||||
},
|
||||
"Set": {
|
||||
"name": "Set",
|
||||
"kind": "alias",
|
||||
"path": "docforge.renderers.mkdocs_renderer.Set",
|
||||
"signature": "<bound method Alias.signature of Alias('Set', 'typing.Set')>",
|
||||
"docstring": null
|
||||
},
|
||||
"Module": {
|
||||
"name": "Module",
|
||||
"kind": "class",
|
||||
@@ -2605,6 +2575,29 @@
|
||||
"docstring": "Get all top-level objects in the module.\n\nReturns:\n An iterable of DocObject instances."
|
||||
}
|
||||
}
|
||||
},
|
||||
"MkDocsRenderer": {
|
||||
"name": "MkDocsRenderer",
|
||||
"kind": "class",
|
||||
"path": "docforge.renderers.mkdocs_renderer.MkDocsRenderer",
|
||||
"signature": "<bound method Class.signature of Class('MkDocsRenderer', 16, 168)>",
|
||||
"docstring": "Renderer that generates Markdown source files formatted for the MkDocs\n'mkdocstrings' plugin.",
|
||||
"members": {
|
||||
"name": {
|
||||
"name": "name",
|
||||
"kind": "attribute",
|
||||
"path": "docforge.renderers.mkdocs_renderer.MkDocsRenderer.name",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
},
|
||||
"generate_sources": {
|
||||
"name": "generate_sources",
|
||||
"kind": "function",
|
||||
"path": "docforge.renderers.mkdocs_renderer.MkDocsRenderer.generate_sources",
|
||||
"signature": "<bound method Function.signature of Function('generate_sources', 27, 60)>",
|
||||
"docstring": "Produce a set of Markdown files in the output directory based on the\nprovided Project models.\n\nArgs:\n project: The project models to render.\n out_dir: Target directory for documentation files.\n module_is_source: Module is the source folder and to be treated as the root folder."
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user