9 Commits

Author SHA1 Message Date
8c6c46caf2 feat: add wiki build kind with file-structure-derived navigation
- add build_wiki_nav deriving MkDocs nav from docs/wiki file structure
  (index.md -> Home, numeric prefixes stripped and title-cased, nested
  dirs become groups, natural ordering)
- add --wiki / --wiki-dir to build; wiki-only builds need no --module
- merge wiki nav before generated lib/api nav; wiki Home replaces the
  nav spec Home entry
- add mkdocs.wiki.yml template fragment and nav/cli tests
- dogfood doc-forge's own docs/wiki and regenerate site output
2026-09-11 23:38:23 +05:30
bacf17b930 feat: add --api OpenAPI build mode with docs/api scheme and lib-prefixed nav 2026-09-11 05:37:56 +05:30
17e8628197 docs: nest generated docs under docs/lib and docs/mcp 2026-09-10 21:15:11 +05:30
a1c5f046d4 docs: output generated sources under docs/lib and docs/mcp 2026-09-10 21:11:30 +05:30
d4b79cf95a ignore coverage.xml test artifact 2026-09-10 20:21:23 +05:30
0129268cd3 standardize packaging, tooling, docs, CI, and licensing 2026-09-10 18:49:04 +05:30
8253c25928 updated docs strings and added README.md 2026-03-08 17:59:55 +05:30
e8e16f3996 code blocks with backticks for more control on formatting 2026-03-08 15:32:46 +05:30
f73282b997 formatting for examples and header sections 2026-03-08 15:05:38 +05:30
162 changed files with 5555 additions and 3437 deletions

View File

@@ -32,6 +32,26 @@ steps:
echo "🆕 New version detected: $PACKAGE_NAME==$VERSION" echo "🆕 New version detected: $PACKAGE_NAME==$VERSION"
fi fi
- name: quality-gate
image: python:3.13-slim
environment:
PIP_REPO_URL:
from_secret: PIP_REPO_URL
PIP_USERNAME:
from_secret: PIP_USERNAME
PIP_PASSWORD:
from_secret: PIP_PASSWORD
commands:
- pip install --upgrade pip build
- |
AUTH_URL="https://${PIP_USERNAME}:${PIP_PASSWORD}@$(echo "${PIP_REPO_URL#*://}" | sed 's:/*$::')/simple"
pip install --index-url "$AUTH_URL" --extra-index-url https://pypi.org/simple/ -U ".[dev]"
- echo "🛡️ Running quality gate..."
- python -m black --check .
- python -m ruff check .
- python -m mypy
- python -m pytest
- name: build-package - name: build-package
image: python:3.13-slim image: python:3.13-slim
commands: commands:

5
.gitignore vendored
View File

@@ -87,3 +87,8 @@ Thumbs.db
# ========================= # =========================
.env .env
.env.* .env.*
# =========================
# Testing artifacts
# =========================
coverage.xml

21
CHANGELOG.md Normal file
View File

@@ -0,0 +1,21 @@
# Changelog
All notable changes to this project will be documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
## [Unreleased]
### Added
- `py.typed` marker for PEP 561 type information.
- `.drone.yml` CI with a quality-gate step (black, ruff, mypy, pytest).
- MIT `LICENSE`.
### Changed
- Standardized `pyproject.toml` (canonical packaging, lint tool config, extras).
- Pinned the `mcp` extra to `mcp>=1.0.0,<2.0.0` to restore compatibility with
the current MCP server API used by doc-forge.
### Fixed
- Stub fixes for typed API surfaces.

21
LICENSE Normal file
View File

@@ -0,0 +1,21 @@
MIT License
Copyright (c) 2026 Aetoskia Platform
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

539
README.md
View File

@@ -1,5 +1,7 @@
# docforge # docforge
# Summary
Renderer-agnostic Python documentation compiler that converts Python docstrings Renderer-agnostic Python documentation compiler that converts Python docstrings
into structured documentation for both humans (MkDocs) and machines (MCP / AI agents). into structured documentation for both humans (MkDocs) and machines (MCP / AI agents).
@@ -9,137 +11,116 @@ outputs without executing user code.
--- ---
## Installation # Installation
Install using pip: Install using pip:
pip install doc-forge ```bash
pip install doc-forge
```
--- ---
## Quick start # CLI usage
Generate a MkDocs site from a Python package: ## Generate an MkDocs site from a Python package:
doc-forge build --mkdocs --module my_package ```bash
doc-forge build --mkdocs --module my_package
```
Generate MCP JSON documentation: ## Generate MCP JSON documentation:
doc-forge build --mcp --module my_package ```bash
doc-forge build --mcp --module my_package
```
Serve documentation locally:
doc-forge serve --mkdocs --module my_package ## Generate MkDocs site and MCP JSON documentation:
```bash
doc-forge build --mcp --mkdocs --module my_package
```
## Serve MkDocs locally:
```bash
doc-forge serve --mkdocs --module my_package
```
## Serve MCP locally:
```bash
doc-forge serve --mcp --module my_package
```
--- ---
## Core concepts # Core concepts
**Loader**
## Loader
Extracts symbols, signatures, and docstrings using static analysis. Extracts symbols, signatures, and docstrings using static analysis.
**Semantic model** ## Semantic model
Structured, renderer-agnostic representation of the API. Structured, renderer-agnostic representation of the API.
**Renderer** ## Renderer
Converts the semantic model into output formats such as MkDocs or MCP JSON. Converts the semantic model into output formats such as MkDocs or MCP JSON.
**Symbol** ## Symbol
Any documentable object
Any documentable object: - module
- class
- module - function
- class - method
- function - property
- method - attribute
- property
- attribute
--- ---
## Architecture # Architecture
`doc-forge` follows a compiler architecture: `doc-forge` follows a compiler architecture:
Front-end: ## Front-end:
Static analysis of modules, classes, functions, type hints, and docstrings. Static analysis of modules, classes, functions, type hints, and docstrings.
Middle-end: ## Middle-end:
Builds a semantic model describing symbols and relationships. Builds a semantic model describing symbols and relationships.
Back-end: ## Back-end:
Renders documentation using interchangeable renderers. Renders documentation using interchangeable renderers.
This architecture ensures deterministic documentation generation. This architecture ensures deterministic documentation generation.
--- ---
## Rendering pipeline # Rendering pipeline
Typical flow: Typical flow:
Python package Python package
↓ |
Loader (static analysis) Loader (static analysis)
↓ |
Semantic model Semantic model
↓ |
Renderer Renderer
↓ |
MkDocs site or MCP JSON MkDocs site or MCP JSON
--- ---
## CLI usage
Build MkDocs documentation:
doc-forge build --mkdocs --module my_package
Build MCP documentation:
doc-forge build --mcp --module my_package
Serve MkDocs locally:
doc-forge serve --module my_package
---
## Public API
Loaders:
GriffeLoader
discover_module_paths
Renderers:
MkDocsRenderer
MCPRenderer
CLI:
main
Models:
models
---
# Google-Styled Doc-Forge Convention (GSDFC) # Google-Styled Doc-Forge Convention (GSDFC)
GSDFC defines how docstrings must be written so they render correctly in MkDocs and remain machine-parsable by doc-forge and AI tooling. GSDFC defines how docstrings must be written so they render correctly in MkDocs and remain machine-parsable by doc-forge and AI tooling.
- Docstrings are the single source of truth. - Docstrings are the single source of truth.
- doc-forge compiles docstrings but does not generate documentation content. - `doc-forge` compiles docstrings but does not generate documentation content.
- Documentation follows the Python import hierarchy. - Documentation follows the Python import hierarchy.
- Every public symbol should have a complete and accurate docstring. - Every public symbol should have a complete and accurate docstring.
@@ -149,34 +130,110 @@ GSDFC defines how docstrings must be written so they render correctly in MkDocs
- Use **Markdown headings** at package and module level. - Use **Markdown headings** at package and module level.
- Use **Google-style structured sections** at class, function, and method level. - Use **Google-style structured sections** at class, function, and method level.
- Indent section contents using four spaces.
- Use type hints in signatures instead of duplicating types in prose. - Use type hints in signatures instead of duplicating types in prose.
- Write summaries in imperative form. - Write summaries in imperative form.
- Sections are separated by ```---``` - Sections are separated by `---`
--- ---
## Package docstrings # Notes subsection grouping
- Package docstrings act as the documentation home page. Group related information using labeled subsections.
Example:
Notes:
**Guarantees:**
- deterministic behavior
**Lifecycle:**
- created during initialization
- reused across executions
**Thread safety:**
- safe for concurrent reads
---
# Example formatting
- Use indentation for examples.
- Indent section contents using four spaces.
- Use code blocks for example code.
Example:
Single example:
Example:
```python
foo = Foo("example")
process(foo, multiplier=2)
```
Multiple examples:
Example:
Create foo:
```python
foo = Foo("example")
```
Run engine:
```python
engine = BarEngine([foo])
engine.run()
```
Avoid fenced code blocks inside structured sections.
---
# Separator rules
Use horizontal separators only at docstring root level to separate sections:
```markdown
---
```
Allowed locations:
- package docstrings
- module docstrings
- major documentation sections
Do not use separators inside code sections.
---
# Package docstrings
Package docstrings act as the documentation home page.
Recommended sections: Recommended sections:
## Summary # Summary
## Installation # Installation
## Quick start # Quick start
## Core concepts # CLI usage
## Architecture # Core concepts
## Rendering pipeline # Architecture
## CLI usage # Rendering pipeline
## Public API # Examples
## Examples # Notes
## Notes
Example: Example:
Package Doc String: Package Doc String:
''' '''
# Summary
Foo-bar processing framework. Foo-bar processing framework.
Provides tools for defining Foo objects and executing Bar pipelines. Provides tools for defining Foo objects and executing Bar pipelines.
@@ -185,47 +242,44 @@ Example:
# Installation # Installation
pip install foo-bar ```bash
pip install foo-bar
```
--- ---
# Quick start # Quick start
from foobar import Foo, BarEngine ```python
from foobar import Foo, BarEngine
foo = Foo("example") foo = Foo("example")
engine = BarEngine([foo]) engine = BarEngine([foo])
result = engine.run() result = engine.run()
```
---
# Public API
Foo
Bar
BarEngine
--- ---
''' '''
--- ---
## Module docstrings # Module docstrings
- Module docstrings describe a subsystem. Module docstrings describe a subsystem.
Recommended sections: Recommended sections:
## Summary # Summary
## Examples # Examples
## Notes # Notes
## Public API
Example: Example:
Module Doc String: Module Doc String:
''' '''
# Summary
Foo execution subsystem. Foo execution subsystem.
Provides utilities for executing Foo objects through Bar stages. Provides utilities for executing Foo objects through Bar stages.
@@ -234,6 +288,7 @@ Example:
Example: Example:
```python
from foobar.engine import BarEngine from foobar.engine import BarEngine
from foobar.foo import Foo from foobar.foo import Foo
@@ -241,15 +296,16 @@ Example:
engine = BarEngine([foo]) engine = BarEngine([foo])
engine.run() engine.run()
```
--- ---
''' '''
--- ---
## Class docstrings # Class docstrings
- Class docstrings define object responsibility, lifecycle, and attributes. Class docstrings define object responsibility, lifecycle, and attributes.
Recommended sections: Recommended sections:
@@ -261,64 +317,72 @@ Recommended sections:
Example: Example:
Simple Foo: Simple Foo:
class Foo: ```python
''' class Foo:
Represents a unit of work. '''
Represents a unit of work.
Attributes: Attributes:
name (str): name (str):
Identifier of the foo instance. Identifier of the foo instance.
value (int): value (int):
Numeric value associated with foo. Numeric value associated with foo.
Notes: Notes:
Guarantees: Guarantees:
- instances are immutable after creation - instances are immutable after creation
Lifecycle: Lifecycle:
- create instance - create instance
- pass to processing engine - pass to processing engine
Example: Example:
Create and inspect a Foo: Create and inspect a Foo:
foo = Foo("example", value=42) ```python
print(foo.name) foo = Foo("example", value=42)
''' print(foo.name)
```
'''
```
Complex Bar: Complex Bar:
class BarEngine: ```python
''' class BarEngine:
Executes Foo objects through Bar stages. '''
Executes Foo objects through Bar stages.
Attributes: Attributes:
foos (tuple[Foo, ...]): foos (tuple[Foo, ...]):
Foo instances managed by the engine. Foo instances managed by the engine.
Notes: Notes:
Guarantees: Guarantees:
- deterministic execution order - deterministic execution order
Example: Example:
Run engine: Run engine:
foo1 = Foo("a") ```python
foo2 = Foo("b") foo1 = Foo("a")
foo2 = Foo("b")
engine = BarEngine([foo1, foo2]) engine = BarEngine([foo1, foo2])
engine.run() engine.run()
''' ```
'''
```
--- ---
## Function and method docstrings # Function and method docstrings
- Function docstrings define API contracts. Function docstrings define API contracts.
Recommended sections: Recommended sections:
@@ -332,79 +396,90 @@ Recommended sections:
Example: Example:
Simple process method: Simple process method:
def process(foo: Foo, multiplier: int) -> int: ```python
''' def process(foo: Foo, multiplier: int) -> int:
Process a Foo instance. '''
Process a Foo instance.
Args: Args:
foo (Foo): foo (Foo):
Foo instance to process. Foo instance to process.
multiplier (int): multiplier (int):
Value used to scale foo. Value used to scale foo.
Returns: Returns:
int: int:
Processed result. Processed result.
Raises: Raises:
ValueError: ValueError:
If multiplier is negative. If multiplier is negative.
Notes: Notes:
Guarantees: Guarantees:
- foo is not modified - foo is not modified
Example: Example:
Process foo: Process foo:
foo = Foo("example", value=10) ```python
foo = Foo("example", value=10)
result = process(foo, multiplier=2) result = process(foo, multiplier=2)
print(result) print(result)
''' ```
'''
```
Multiple Examples: Multiple Examples:
def combine(foo_a: Foo, foo_b: Foo) -> Foo: ```python
''' def combine(foo_a: Foo, foo_b: Foo) -> Foo:
Combine two Foo instances. '''
Combine two Foo instances.
Args: Args:
foo_a (Foo): foo_a (Foo):
First foo. First foo.
foo_b (Foo): foo_b (Foo):
Second foo. Second foo.
Returns: Returns:
Foo: Foo:
Combined foo. Combined foo.
Example: Example:
Basic usage: Basic usage:
foo1 = Foo("a") ```python
foo2 = Foo("b") foo1 = Foo("a")
foo2 = Foo("b")
combined = combine(foo1, foo2) combined = combine(foo1, foo2)
```
Pipeline usage: Pipeline usage:
engine = BarEngine([foo1, foo2]) ```python
engine.run() engine = BarEngine([foo1, foo2])
''' engine.run()
```
'''
```
--- ---
## Property docstrings # Property docstrings
- Properties must document return values. Properties must document return values.
Example: Example:
Property Doc String: Property Doc String:
```python
@property @property
def foos(self) -> tuple[Foo, ...]: def foos(self) -> tuple[Foo, ...]:
''' '''
@@ -415,20 +490,24 @@ Example:
Stored foo objects. Stored foo objects.
Example: Example:
```python
container = FooContainer() container = FooContainer()
foos = container.foos foos = container.foos
```
''' '''
```
--- ---
## Attribute documentation # Attribute documentation
- Document attributes in class docstrings using Attributes:. Document attributes in class docstrings using `Attributes:`.
Example: Example:
Attribute Doc String: Attribute Doc String:
```python
''' '''
Represents a processing stage. Represents a processing stage.
@@ -439,77 +518,11 @@ Example:
enabled (bool): enabled (bool):
Whether the stage is active. Whether the stage is active.
''' '''
```
--- ---
## Notes subsection grouping # Parsing guarantees
- Group related information using labeled subsections.
Example:
Notes Example:
Notes:
**Guarantees:**
- deterministic behavior
**Lifecycle:**
- created during initialization
- reused across executions
**Thread safety:**
- safe for concurrent reads
---
## Example formatting
- Use indentation for examples.
Example:
Single example:
Example:
foo = Foo("example")
process(foo, multiplier=2)
Multiple examples:
Example:
Create foo:
foo = Foo("example")
Run engine:
engine = BarEngine([foo])
engine.run()
Avoid fenced code blocks inside structured sections.
---
## Separator rules
Use horizontal separators only at docstring root level to separate sections:
---
Allowed locations:
- package docstrings
- module docstrings
- major documentation sections
Do not use separators inside code sections.
---
## Parsing guarantees
GSDFC ensures doc-forge can deterministically extract: GSDFC ensures doc-forge can deterministically extract:

View File

@@ -1,26 +1,30 @@
home: index.md home: lib/index.md
groups: groups:
Loaders: Loaders:
- loaders/index.md - lib/loaders/index.md
- loaders/griffe_loader.md - lib/loaders/griffe_loader.md
Models: Models:
- models/index.md - lib/models/index.md
- models/module.md - lib/models/module.md
- models/object.md - lib/models/object.md
- models/project.md - lib/models/project.md
Navigation: Navigation:
- nav/index.md - lib/nav/index.md
- nav/spec.md - lib/nav/spec.md
- nav/resolver.md - lib/nav/resolver.md
- nav/mkdocs.md - lib/nav/mkdocs.md
Renderers: Renderers:
- renderers/index.md - lib/renderers/index.md
- renderers/base.md - lib/renderers/base.md
- renderers/mkdocs_renderer.md - lib/renderers/mkdocs_renderer.md
- renderers/mcp_renderer.md - lib/renderers/mcp_renderer.md
CLI: CLI:
- cli/index.md - lib/cli/index.md
- cli/main.md - lib/cli/main.md
- cli/commands.md - lib/cli/commands.md
- cli/mcp_utils.md - lib/cli/api_utils.md
- cli/mkdocs_utils.md - lib/cli/mcp_utils.md
- lib/cli/mkdocs_utils.md
icon:
logo: material/file-document-multiple
repo: fontawesome/brands/github

View File

@@ -1,4 +1,6 @@
""" """
# Summary
Renderer-agnostic Python documentation compiler that converts Python docstrings Renderer-agnostic Python documentation compiler that converts Python docstrings
into structured documentation for both humans (MkDocs) and machines (MCP / AI agents). into structured documentation for both humans (MkDocs) and machines (MCP / AI agents).
@@ -8,137 +10,116 @@ outputs without executing user code.
--- ---
## Installation # Installation
Install using pip: Install using pip:
pip install doc-forge ```bash
pip install doc-forge
```
--- ---
## Quick start # CLI usage
Generate a MkDocs site from a Python package: ## Generate an MkDocs site from a Python package:
doc-forge build --mkdocs --module my_package ```bash
doc-forge build --mkdocs --module my_package
```
Generate MCP JSON documentation: ## Generate MCP JSON documentation:
doc-forge build --mcp --module my_package ```bash
doc-forge build --mcp --module my_package
```
Serve documentation locally:
doc-forge serve --mkdocs --module my_package ## Generate MkDocs site and MCP JSON documentation:
```bash
doc-forge build --mcp --mkdocs --module my_package
```
## Serve MkDocs locally:
```bash
doc-forge serve --mkdocs --module my_package
```
## Serve MCP locally:
```bash
doc-forge serve --mcp --module my_package
```
--- ---
## Core concepts # Core concepts
**Loader**
## Loader
Extracts symbols, signatures, and docstrings using static analysis. Extracts symbols, signatures, and docstrings using static analysis.
**Semantic model** ## Semantic model
Structured, renderer-agnostic representation of the API. Structured, renderer-agnostic representation of the API.
**Renderer** ## Renderer
Converts the semantic model into output formats such as MkDocs or MCP JSON. Converts the semantic model into output formats such as MkDocs or MCP JSON.
**Symbol** ## Symbol
Any documentable object
Any documentable object: - module
- class
- module - function
- class - method
- function - property
- method - attribute
- property
- attribute
--- ---
## Architecture # Architecture
`doc-forge` follows a compiler architecture: `doc-forge` follows a compiler architecture:
Front-end: ## Front-end:
Static analysis of modules, classes, functions, type hints, and docstrings. Static analysis of modules, classes, functions, type hints, and docstrings.
Middle-end: ## Middle-end:
Builds a semantic model describing symbols and relationships. Builds a semantic model describing symbols and relationships.
Back-end: ## Back-end:
Renders documentation using interchangeable renderers. Renders documentation using interchangeable renderers.
This architecture ensures deterministic documentation generation. This architecture ensures deterministic documentation generation.
--- ---
## Rendering pipeline # Rendering pipeline
Typical flow: Typical flow:
Python package Python package
↓ |
Loader (static analysis) Loader (static analysis)
↓ |
Semantic model Semantic model
↓ |
Renderer Renderer
↓ |
MkDocs site or MCP JSON MkDocs site or MCP JSON
--- ---
## CLI usage
Build MkDocs documentation:
doc-forge build --mkdocs --module my_package
Build MCP documentation:
doc-forge build --mcp --module my_package
Serve MkDocs locally:
doc-forge serve --module my_package
---
## Public API
Loaders:
GriffeLoader
discover_module_paths
Renderers:
MkDocsRenderer
MCPRenderer
CLI:
main
Models:
models
---
# Google-Styled Doc-Forge Convention (GSDFC) # Google-Styled Doc-Forge Convention (GSDFC)
GSDFC defines how docstrings must be written so they render correctly in MkDocs and remain machine-parsable by doc-forge and AI tooling. GSDFC defines how docstrings must be written so they render correctly in MkDocs and remain machine-parsable by doc-forge and AI tooling.
- Docstrings are the single source of truth. - Docstrings are the single source of truth.
- doc-forge compiles docstrings but does not generate documentation content. - `doc-forge` compiles docstrings but does not generate documentation content.
- Documentation follows the Python import hierarchy. - Documentation follows the Python import hierarchy.
- Every public symbol should have a complete and accurate docstring. - Every public symbol should have a complete and accurate docstring.
@@ -148,34 +129,110 @@ GSDFC defines how docstrings must be written so they render correctly in MkDocs
- Use **Markdown headings** at package and module level. - Use **Markdown headings** at package and module level.
- Use **Google-style structured sections** at class, function, and method level. - Use **Google-style structured sections** at class, function, and method level.
- Indent section contents using four spaces.
- Use type hints in signatures instead of duplicating types in prose. - Use type hints in signatures instead of duplicating types in prose.
- Write summaries in imperative form. - Write summaries in imperative form.
- Sections are separated by ```---``` - Sections are separated by `---`
--- ---
## Package docstrings # Notes subsection grouping
- Package docstrings act as the documentation home page. Group related information using labeled subsections.
Example:
Notes:
**Guarantees:**
- deterministic behavior
**Lifecycle:**
- created during initialization
- reused across executions
**Thread safety:**
- safe for concurrent reads
---
# Example formatting
- Use indentation for examples.
- Indent section contents using four spaces.
- Use code blocks for example code.
Example:
Single example:
Example:
```python
foo = Foo("example")
process(foo, multiplier=2)
```
Multiple examples:
Example:
Create foo:
```python
foo = Foo("example")
```
Run engine:
```python
engine = BarEngine([foo])
engine.run()
```
Avoid fenced code blocks inside structured sections.
---
# Separator rules
Use horizontal separators only at docstring root level to separate sections:
```markdown
---
```
Allowed locations:
- package docstrings
- module docstrings
- major documentation sections
Do not use separators inside code sections.
---
# Package docstrings
Package docstrings act as the documentation home page.
Recommended sections: Recommended sections:
## Summary # Summary
## Installation # Installation
## Quick start # Quick start
## Core concepts # CLI usage
## Architecture # Core concepts
## Rendering pipeline # Architecture
## CLI usage # Rendering pipeline
## Public API # Examples
## Examples # Notes
## Notes
Example: Example:
Package Doc String: Package Doc String:
''' '''
# Summary
Foo-bar processing framework. Foo-bar processing framework.
Provides tools for defining Foo objects and executing Bar pipelines. Provides tools for defining Foo objects and executing Bar pipelines.
@@ -184,47 +241,44 @@ Example:
# Installation # Installation
pip install foo-bar ```bash
pip install foo-bar
```
--- ---
# Quick start # Quick start
from foobar import Foo, BarEngine ```python
from foobar import Foo, BarEngine
foo = Foo("example") foo = Foo("example")
engine = BarEngine([foo]) engine = BarEngine([foo])
result = engine.run() result = engine.run()
```
---
# Public API
Foo
Bar
BarEngine
--- ---
''' '''
--- ---
## Module docstrings # Module docstrings
- Module docstrings describe a subsystem. Module docstrings describe a subsystem.
Recommended sections: Recommended sections:
## Summary # Summary
## Examples # Examples
## Notes # Notes
## Public API
Example: Example:
Module Doc String: Module Doc String:
''' '''
# Summary
Foo execution subsystem. Foo execution subsystem.
Provides utilities for executing Foo objects through Bar stages. Provides utilities for executing Foo objects through Bar stages.
@@ -233,6 +287,7 @@ Example:
Example: Example:
```python
from foobar.engine import BarEngine from foobar.engine import BarEngine
from foobar.foo import Foo from foobar.foo import Foo
@@ -240,15 +295,16 @@ Example:
engine = BarEngine([foo]) engine = BarEngine([foo])
engine.run() engine.run()
```
--- ---
''' '''
--- ---
## Class docstrings # Class docstrings
- Class docstrings define object responsibility, lifecycle, and attributes. Class docstrings define object responsibility, lifecycle, and attributes.
Recommended sections: Recommended sections:
@@ -260,64 +316,72 @@ Recommended sections:
Example: Example:
Simple Foo: Simple Foo:
class Foo: ```python
''' class Foo:
Represents a unit of work. '''
Represents a unit of work.
Attributes: Attributes:
name (str): name (str):
Identifier of the foo instance. Identifier of the foo instance.
value (int): value (int):
Numeric value associated with foo. Numeric value associated with foo.
Notes: Notes:
Guarantees: Guarantees:
- instances are immutable after creation - instances are immutable after creation
Lifecycle: Lifecycle:
- create instance - create instance
- pass to processing engine - pass to processing engine
Example: Example:
Create and inspect a Foo: Create and inspect a Foo:
foo = Foo("example", value=42) ```python
print(foo.name) foo = Foo("example", value=42)
''' print(foo.name)
```
'''
```
Complex Bar: Complex Bar:
class BarEngine: ```python
''' class BarEngine:
Executes Foo objects through Bar stages. '''
Executes Foo objects through Bar stages.
Attributes: Attributes:
foos (tuple[Foo, ...]): foos (tuple[Foo, ...]):
Foo instances managed by the engine. Foo instances managed by the engine.
Notes: Notes:
Guarantees: Guarantees:
- deterministic execution order - deterministic execution order
Example: Example:
Run engine: Run engine:
foo1 = Foo("a") ```python
foo2 = Foo("b") foo1 = Foo("a")
foo2 = Foo("b")
engine = BarEngine([foo1, foo2]) engine = BarEngine([foo1, foo2])
engine.run() engine.run()
''' ```
'''
```
--- ---
## Function and method docstrings # Function and method docstrings
- Function docstrings define API contracts. Function docstrings define API contracts.
Recommended sections: Recommended sections:
@@ -331,79 +395,90 @@ Recommended sections:
Example: Example:
Simple process method: Simple process method:
def process(foo: Foo, multiplier: int) -> int: ```python
''' def process(foo: Foo, multiplier: int) -> int:
Process a Foo instance. '''
Process a Foo instance.
Args: Args:
foo (Foo): foo (Foo):
Foo instance to process. Foo instance to process.
multiplier (int): multiplier (int):
Value used to scale foo. Value used to scale foo.
Returns: Returns:
int: int:
Processed result. Processed result.
Raises: Raises:
ValueError: ValueError:
If multiplier is negative. If multiplier is negative.
Notes: Notes:
Guarantees: Guarantees:
- foo is not modified - foo is not modified
Example: Example:
Process foo: Process foo:
foo = Foo("example", value=10) ```python
foo = Foo("example", value=10)
result = process(foo, multiplier=2) result = process(foo, multiplier=2)
print(result) print(result)
''' ```
'''
```
Multiple Examples: Multiple Examples:
def combine(foo_a: Foo, foo_b: Foo) -> Foo: ```python
''' def combine(foo_a: Foo, foo_b: Foo) -> Foo:
Combine two Foo instances. '''
Combine two Foo instances.
Args: Args:
foo_a (Foo): foo_a (Foo):
First foo. First foo.
foo_b (Foo): foo_b (Foo):
Second foo. Second foo.
Returns: Returns:
Foo: Foo:
Combined foo. Combined foo.
Example: Example:
Basic usage: Basic usage:
foo1 = Foo("a") ```python
foo2 = Foo("b") foo1 = Foo("a")
foo2 = Foo("b")
combined = combine(foo1, foo2) combined = combine(foo1, foo2)
```
Pipeline usage: Pipeline usage:
engine = BarEngine([foo1, foo2]) ```python
engine.run() engine = BarEngine([foo1, foo2])
''' engine.run()
```
'''
```
--- ---
## Property docstrings # Property docstrings
- Properties must document return values. Properties must document return values.
Example: Example:
Property Doc String: Property Doc String:
```python
@property @property
def foos(self) -> tuple[Foo, ...]: def foos(self) -> tuple[Foo, ...]:
''' '''
@@ -414,20 +489,24 @@ Example:
Stored foo objects. Stored foo objects.
Example: Example:
```python
container = FooContainer() container = FooContainer()
foos = container.foos foos = container.foos
```
''' '''
```
--- ---
## Attribute documentation # Attribute documentation
- Document attributes in class docstrings using Attributes:. Document attributes in class docstrings using `Attributes:`.
Example: Example:
Attribute Doc String: Attribute Doc String:
```python
''' '''
Represents a processing stage. Represents a processing stage.
@@ -438,77 +517,11 @@ Example:
enabled (bool): enabled (bool):
Whether the stage is active. Whether the stage is active.
''' '''
```
--- ---
## Notes subsection grouping # Parsing guarantees
- Group related information using labeled subsections.
Example:
Notes Example:
Notes:
**Guarantees:**
- deterministic behavior
**Lifecycle:**
- created during initialization
- reused across executions
**Thread safety:**
- safe for concurrent reads
---
## Example formatting
- Use indentation for examples.
Example:
Single example:
Example:
foo = Foo("example")
process(foo, multiplier=2)
Multiple examples:
Example:
Create foo:
foo = Foo("example")
Run engine:
engine = BarEngine([foo])
engine.run()
Avoid fenced code blocks inside structured sections.
---
## Separator rules
Use horizontal separators only at docstring root level to separate sections:
---
Allowed locations:
- package docstrings
- module docstrings
- major documentation sections
Do not use separators inside code sections.
---
## Parsing guarantees
GSDFC ensures doc-forge can deterministically extract: GSDFC ensures doc-forge can deterministically extract:

View File

@@ -1,7 +1,7 @@
from .loaders import GriffeLoader, discover_module_paths
from .renderers import MkDocsRenderer, MCPRenderer
from .cli import main
from . import models from . import models
from .cli import main
from .loaders import GriffeLoader, discover_module_paths
from .renderers import MCPRenderer, MkDocsRenderer
__all__ = [ __all__ = [
"GriffeLoader", "GriffeLoader",

View File

@@ -1,9 +1,11 @@
""" """
# Summary
Command line interface entry point for doc-forge. Command line interface entry point for doc-forge.
This module exposes the primary CLI entry function used by the This module exposes the primary CLI entry function used by the
``doc-forge`` command. The actual command implementation resides in `doc-forge` command. The actual command implementation resides in
``docforge.cli.main``, while this module provides a stable import path `docforge.cli.main`, while this module provides a stable import path
for external tools and the package entry point configuration. for external tools and the package entry point configuration.
The CLI is responsible for orchestrating documentation workflows such as The CLI is responsible for orchestrating documentation workflows such as
@@ -13,23 +15,26 @@ servers.
--- ---
Typical usage # Typical usage
-------------
The CLI is normally invoked through the installed command: The CLI is normally invoked through the installed command:
doc-forge <command> [options] ```bash
doc-forge <command> [options]
```
Programmatic invocation is also possible: Programmatic invocation is also possible:
Example:
```python
from docforge.cli import main from docforge.cli import main
main() main()
```
--- ---
""" """
from .main import main from .main import main
__all__ = [ __all__ = ["main"]
"main"
]

View File

@@ -1,5 +1,3 @@
from .main import main from .main import main
__all__ = [ __all__ = ["main"]
"main"
]

114
docforge/cli/api_utils.py Normal file
View File

@@ -0,0 +1,114 @@
"""
# Summary
Utilities for building API documentation from an OpenAPI specification.
"""
import json
from dataclasses import dataclass
from pathlib import Path
import click
SWAGGER_SPEC_FILENAME = "openapi.json"
@dataclass
class OpenAPIMetadata:
"""
Metadata derived from the ``info`` block of an OpenAPI specification.
Attributes:
site_name: Spec title, used as the MkDocs site name.
site_description: Spec description, used as the site description.
site_author: Contact name (fallback: contact email), used as the
site author.
"""
site_name: str
site_description: str | None
site_author: str | None
def load_openapi_spec(spec_path: Path) -> dict:
"""
Load and validate an OpenAPI specification from a JSON file.
Args:
spec_path: Path to the OpenAPI JSON specification file.
Returns:
dict:
The parsed OpenAPI specification.
Raises:
click.ClickException:
If the file cannot be read or the ``info`` block is invalid.
"""
if not spec_path.exists():
raise click.ClickException(f"OpenAPI spec not found: {spec_path}")
try:
data = json.loads(spec_path.read_text(encoding="utf-8"))
except (json.JSONDecodeError, OSError) as exc:
raise click.ClickException(f"Unable to read OpenAPI spec: {exc}") from exc
if not isinstance(data, dict):
raise click.ClickException("OpenAPI spec must be a JSON mapping")
info = data.get("info")
if not isinstance(info, dict) or not isinstance(info.get("title"), str):
raise click.ClickException("OpenAPI spec missing 'info.title'")
return data
def derive_metadata(spec: dict) -> OpenAPIMetadata:
"""
Derive MkDocs site metadata from an OpenAPI spec ``info`` block.
Args:
spec: Parsed OpenAPI specification.
Returns:
OpenAPIMetadata:
Site name, description, and author derived from the spec.
"""
info = spec["info"]
contact = info.get("contact")
if isinstance(contact, dict):
author = contact.get("name") or contact.get("email")
else:
author = None
return OpenAPIMetadata(
site_name=info.get("title", ""),
site_description=info.get("description"),
site_author=author,
)
def generate_api_sources(spec: dict, docs_dir: Path) -> None:
"""
Generate swagger-enabled Markdown sources and the spec copy.
The specification is written as ``openapi.json`` inside ``docs_dir`` and
an ``index.md`` embedding the swagger UI is generated alongside it.
Args:
spec: Parsed OpenAPI specification.
docs_dir: Directory (for example ``docs/api``) where the swagger
sources are written.
"""
docs_dir.mkdir(parents=True, exist_ok=True)
spec_path = docs_dir / SWAGGER_SPEC_FILENAME
spec_json = json.dumps(spec, indent=2)
if not spec_path.exists() or spec_path.read_text(encoding="utf-8") != spec_json:
spec_path.write_text(spec_json, encoding="utf-8")
index_path = docs_dir / "index.md"
content = "# API Reference\n\n" f'<swagger-ui src="{SWAGGER_SPEC_FILENAME}"/>\n'
if not index_path.exists() or index_path.read_text(encoding="utf-8") != content:
index_path.write_text(content, encoding="utf-8")

View File

@@ -0,0 +1,13 @@
from dataclasses import dataclass
from pathlib import Path
from typing import Any
@dataclass
class OpenAPIMetadata:
site_name: str
site_description: str | None
site_author: str | None
def load_openapi_spec(spec_path: Path) -> dict[Any, Any]: ...
def derive_metadata(spec: dict[Any, Any]) -> OpenAPIMetadata: ...
def generate_api_sources(spec: dict[Any, Any], docs_dir: Path) -> None: ...

View File

@@ -1,9 +1,17 @@
import click """
# Summary
Command definitions for the doc-forge CLI.
Provides the CLI structure using Click, including build, serve, and tree commands.
"""
from pathlib import Path from pathlib import Path
from typing import Sequence, Optional
import click
from docforge.cli import api_utils, mcp_utils, mkdocs_utils
from docforge.loaders import GriffeLoader from docforge.loaders import GriffeLoader
from docforge.cli import mkdocs_utils
from docforge.cli import mcp_utils
@click.group() @click.group()
@@ -20,26 +28,71 @@ def cli() -> None:
@cli.command() @cli.command()
@click.option("--mcp", is_flag=True, help="Build MCP resources") @click.option("--mcp", is_flag=True, help="Build MCP resources")
@click.option("--mkdocs", is_flag=True, help="Build MkDocs site") @click.option("--mkdocs", is_flag=True, help="Build MkDocs site")
@click.option("--module-is-source", is_flag=True, help="Module is source folder and to be treated as root folder") @click.option("--api", is_flag=True, help="Build API docs from an OpenAPI spec")
@click.option(
"--wiki", is_flag=True, help="Include a hand-written wiki in the MkDocs site"
)
@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("--module", help="Python module to document")
@click.option(
"--openapi-spec",
type=click.Path(path_type=Path),
help="Path to the OpenAPI JSON specification",
)
@click.option("--project-name", help="Project name override") @click.option("--project-name", help="Project name override")
@click.option("--site-name", help="MkDocs site name") @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(
@click.option("--nav", "nav_file", type=click.Path(path_type=Path), default=Path("docforge.nav.yml"), "--docs-dir",
help="Nav spec path") type=click.Path(path_type=Path),
@click.option("--template", type=click.Path(path_type=Path), help="MkDocs template path") default=Path("docs"),
@click.option("--mkdocs-yml", type=click.Path(path_type=Path), default=Path("mkdocs.yml"), help="Output config path") help="MkDocs documentation root",
@click.option("--out-dir", type=click.Path(path_type=Path), default=Path("mcp_docs"), help="MCP output directory") )
@click.option(
"--wiki-dir",
type=click.Path(path_type=Path),
default=Path("docs/wiki"),
help="Hand-written wiki directory included in the MkDocs site",
)
@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",
)
@click.option(
"--out-dir",
type=click.Path(path_type=Path),
default=Path("docs/mcp"),
help="MCP output directory",
)
def build( def build(
mcp: bool, mcp: bool,
mkdocs: bool, mkdocs: bool,
api: bool,
wiki: bool,
module_is_source: bool, module_is_source: bool,
module: Optional[str], module: str | None,
project_name: Optional[str], openapi_spec: Path | None,
site_name: Optional[str], project_name: str | None,
site_name: str | None,
docs_dir: Path, docs_dir: Path,
wiki_dir: Path,
nav_file: Path, nav_file: Path,
template: Optional[Path], template: Path | None,
mkdocs_yml: Path, mkdocs_yml: Path,
out_dir: Path, out_dir: Path,
) -> None: ) -> None:
@@ -47,53 +100,136 @@ def build(
Build documentation artifacts. Build documentation artifacts.
This command performs the full documentation build pipeline: This command performs the full documentation build pipeline:
style of the selected platform, generates renderer-specific
1. Introspects the Python project using Griffe documentation sources, and optionally builds the final output.
2. Generates renderer-specific documentation sources
3. Optionally builds the final documentation output
Depending on the selected options, the build can target: Depending on the selected options, the build can target:
- MkDocs static documentation sites - MkDocs static documentation sites for library reference docs
- Swagger-enabled API docs generated from an OpenAPI spec
- Hand-written wiki pages included in the MkDocs site
- MCP structured documentation resources - MCP structured documentation resources
Args: Args:
mcp: Enable MCP documentation generation. mcp (bool):
mkdocs: Enable MkDocs documentation generation. Enable MCP documentation generation.
module_is_source: Treat the specified module directory as the
project root. mkdocs (bool):
module: Python module import path to document. Enable MkDocs library documentation generation.
project_name: Optional override for the project name.
site_name: Display name for the MkDocs site. api (bool):
docs_dir: Directory where Markdown documentation sources Enable API documentation generation from an OpenAPI spec.
will be generated.
nav_file: Path to the navigation specification file. wiki (bool):
template: Optional custom MkDocs configuration template. Include a hand-written wiki directory in the MkDocs site.
mkdocs_yml: Output path for the generated MkDocs configuration.
out_dir: Output directory for generated MCP resources. module_is_source (bool):
Treat the specified module directory as the project root.
module (Optional[str]):
Python module import path to document.
openapi_spec (Optional[Path]):
Path to the OpenAPI JSON specification used for API docs.
project_name (Optional[str]):
Optional override for the project name.
site_name (Optional[str]):
Display name for the MkDocs site.
docs_dir (Path):
Shared documentation root used as the MkDocs ``docs_dir``.
wiki_dir (Path):
Directory containing hand-written wiki markdown files.
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: 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: if not mcp and not mkdocs and not api and not wiki:
raise click.UsageError("Must specify either --mcp or --mkdocs") raise click.UsageError("Must specify either --mcp, --mkdocs, --wiki, or --api")
if mkdocs: if api:
if not module: if not openapi_spec:
raise click.UsageError("--module is required for MkDocs build") raise click.UsageError("--openapi-spec is required for API build")
if not site_name: if site_name and not mkdocs and not wiki:
site_name = module raise click.UsageError(
"--site-name cannot be overridden for API build; "
"the OpenAPI spec provides the site name"
)
click.echo(f"Generating MkDocs sources in {docs_dir}...") if (mkdocs or mcp) and not module:
mkdocs_utils.generate_sources( raise click.UsageError(
module, "--module is required for MkDocs build"
docs_dir, if mkdocs
project_name, else "--module is required for MCP build"
module_is_source,
) )
spec: dict | None = None
if api:
spec = api_utils.load_openapi_spec(openapi_spec)
if mkdocs:
lib_dir = docs_dir / "lib"
click.echo(f"Generating MkDocs sources in {lib_dir}...")
mkdocs_utils.generate_sources(
module,
lib_dir,
project_name,
module_is_source,
readme_dir=mkdocs_yml.parent,
)
if api:
api_dir = docs_dir / "api"
click.echo(f"Generating API sources in {api_dir}...")
api_utils.generate_api_sources(spec, api_dir)
if mkdocs or api or wiki:
modes: list[str] = []
if mkdocs:
modes.append("lib")
if api:
modes.append("api")
if wiki:
modes.append("wiki")
site_description: str | None = None
site_author: str | None = None
effective_site_name = site_name or module or Path.cwd().name
if api:
metadata = api_utils.derive_metadata(spec)
effective_site_name = metadata.site_name
site_description = metadata.site_description
site_author = metadata.site_author
click.echo(f"Generating MkDocs config {mkdocs_yml}...") click.echo(f"Generating MkDocs config {mkdocs_yml}...")
mkdocs_utils.generate_config(docs_dir, nav_file, template, mkdocs_yml, site_name) mkdocs_utils.generate_config(
docs_dir,
nav_file,
template,
mkdocs_yml,
effective_site_name,
modes=modes,
site_description=site_description,
site_author=site_author,
wiki_dir=wiki_dir if wiki else None,
)
click.echo("Running MkDocs build...") click.echo("Running MkDocs build...")
mkdocs_utils.build(mkdocs_yml) mkdocs_utils.build(mkdocs_yml)
@@ -112,12 +248,22 @@ def build(
@click.option("--mcp", is_flag=True, help="Serve MCP documentation") @click.option("--mcp", is_flag=True, help="Serve MCP documentation")
@click.option("--mkdocs", is_flag=True, help="Serve MkDocs site") @click.option("--mkdocs", is_flag=True, help="Serve MkDocs site")
@click.option("--module", help="Python module to serve") @click.option("--module", help="Python module to serve")
@click.option("--mkdocs-yml", type=click.Path(path_type=Path), default=Path("mkdocs.yml"), help="MkDocs config path") @click.option(
@click.option("--out-dir", type=click.Path(path_type=Path), default=Path("mcp_docs"), help="MCP root directory") "--mkdocs-yml",
type=click.Path(path_type=Path),
default=Path("mkdocs.yml"),
help="MkDocs config path",
)
@click.option(
"--out-dir",
type=click.Path(path_type=Path),
default=Path("docs/mcp"),
help="MCP root directory",
)
def serve( def serve(
mcp: bool, mcp: bool,
mkdocs: bool, mkdocs: bool,
module: Optional[str], module: str | None,
mkdocs_yml: Path, mkdocs_yml: Path,
out_dir: Path, out_dir: Path,
) -> None: ) -> None:
@@ -130,14 +276,24 @@ def serve(
- An MCP server exposing structured documentation resources - An MCP server exposing structured documentation resources
Args: Args:
mcp: Serve documentation using the MCP server. mcp (bool):
mkdocs: Serve the MkDocs development site. Serve documentation using the MCP server.
module: Python module import path to serve via MCP.
mkdocs_yml: Path to the MkDocs configuration file. mkdocs (bool):
out_dir: Root directory containing MCP documentation resources. 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: Raises:
click.UsageError: If invalid or conflicting options are provided. click.UsageError:
If invalid or conflicting options are provided.
""" """
if mcp and mkdocs: if mcp and mkdocs:
raise click.UsageError("Cannot specify both --mcp and --mkdocs") raise click.UsageError("Cannot specify both --mcp and --mkdocs")
@@ -164,7 +320,7 @@ def serve(
) )
def tree( def tree(
module: str, module: str,
project_name: Optional[str], project_name: str | None,
) -> None: ) -> None:
""" """
Display the documentation object tree for a module. Display the documentation object tree for a module.
@@ -174,8 +330,11 @@ def tree(
objects, including modules, classes, functions, and members. objects, including modules, classes, functions, and members.
Args: Args:
module: Python module import path to introspect. module (str):
project_name: Optional name to display as the project root. Python module import path to introspect.
project_name (Optional[str]):
Optional name to display as the project root.
""" """
loader = GriffeLoader() loader = GriffeLoader()
project = loader.load_project([module], project_name) project = loader.load_project([module], project_name)
@@ -196,8 +355,11 @@ def _print_object(obj, indent: str) -> None:
and prints each object with indentation to represent hierarchy. and prints each object with indentation to represent hierarchy.
Args: Args:
obj: Documentation object to print. obj:
indent: Current indentation prefix used for nested members. Documentation object to print.
indent (str):
Current indentation prefix used for nested members.
""" """
click.echo(f"{indent}├── {obj.name}") click.echo(f"{indent}├── {obj.name}")
for member in obj.get_all_members(): for member in obj.get_all_members():

View File

@@ -1,34 +1,36 @@
from click.core import Group
from pathlib import Path from pathlib import Path
from typing import Sequence, Optional, Any from typing import Any
from click.core import Group
cli: Group cli: Group
def build( def build(
mcp: bool, mcp: bool,
mkdocs: bool, mkdocs: bool,
api: bool,
wiki: bool,
module_is_source: bool, module_is_source: bool,
module: Optional[str], module: str | None,
project_name: Optional[str], openapi_spec: Path | None,
site_name: Optional[str], project_name: str | None,
site_name: str | None,
docs_dir: Path, docs_dir: Path,
wiki_dir: Path,
nav_file: Path, nav_file: Path,
template: Optional[Path], template: Path | None,
mkdocs_yml: Path, mkdocs_yml: Path,
out_dir: Path, out_dir: Path,
) -> None: ... ) -> None: ...
def serve( def serve(
mcp: bool, mcp: bool,
mkdocs: bool, mkdocs: bool,
module: Optional[str], module: str | None,
mkdocs_yml: Path, mkdocs_yml: Path,
out_dir: Path, out_dir: Path,
) -> None: ... ) -> None: ...
def tree( def tree(
module: str, module: str,
project_name: Optional[str], project_name: str | None,
) -> None: ... ) -> None: ...
def _print_object(obj: Any, indent: str) -> None: ... def _print_object(obj: Any, indent: str) -> None: ...

View File

@@ -1,8 +1,10 @@
""" """
# Summary
Command-line entry point for the doc-forge CLI. Command-line entry point for the doc-forge CLI.
This module exposes the executable entry point that initializes the 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 from docforge.cli.commands import cli
@@ -13,7 +15,7 @@ def main() -> None:
Run the doc-forge command-line interface. Run the doc-forge command-line interface.
This function initializes and executes the Click CLI application. 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. from the command line.
""" """
cli() cli()

View File

@@ -1,5 +1,13 @@
"""
# Summary
Utilities for working with MCP in the doc-forge CLI.
"""
from pathlib import Path from pathlib import Path
import click import click
from docforge.loaders import GriffeLoader, discover_module_paths from docforge.loaders import GriffeLoader, discover_module_paths
from docforge.renderers import MCPRenderer from docforge.renderers import MCPRenderer
from docforge.servers import MCPServer from docforge.servers import MCPServer
@@ -14,12 +22,17 @@ def generate_resources(module: str, project_name: str | None, out_dir: Path) ->
to the specified output directory. to the specified output directory.
Args: 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. documentation generation.
project_name: Optional override for the project name used in
generated documentation metadata. project_name (Optional[str]):
out_dir: Directory where MCP resources (index.json, nav.json, Optional override for the project name used in generated
and module data) will be written. documentation metadata.
out_dir (Path):
Directory where MCP resources (index.json, nav.json, and module data)
will be written.
""" """
loader = GriffeLoader() loader = GriffeLoader()
discovered_paths = discover_module_paths(module) discovered_paths = discover_module_paths(module)
@@ -37,17 +50,20 @@ def serve(module: str, mcp_root: Path) -> None:
navigation structure, and module documentation through MCP endpoints. navigation structure, and module documentation through MCP endpoints.
Args: Args:
module: Python module import path used to identify the served module (str):
Python module import path used to identify the served
documentation instance. 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/). bundle (index.json, nav.json, and modules/).
Raises: Raises:
click.ClickException: If the MCP documentation bundle is missing click.ClickException:
required files or directories. If the MCP documentation bundle is missing required files or directories.
""" """
if not mcp_root.exists(): if not mcp_root.exists():
raise click.ClickException(f"mcp_docs directory not found: {mcp_root}") raise click.ClickException(f"MCP docs directory not found: {mcp_root}")
required = [ required = [
mcp_root / "index.json", mcp_root / "index.json",

View File

@@ -1,4 +1,6 @@
from pathlib import Path from pathlib import Path
def generate_resources(module: str, project_name: str | None, out_dir: Path) -> None: ... def generate_resources(
module: str, project_name: str | None, out_dir: Path
) -> None: ...
def serve(module: str, mcp_root: Path) -> None: ... def serve(module: str, mcp_root: Path) -> None: ...

View File

@@ -1,10 +1,25 @@
from pathlib import Path """
# Summary
Utilities for working with MkDocs in the doc-forge CLI.
"""
import os
from collections.abc import Iterable
from importlib import resources from importlib import resources
from pathlib import Path
import click import click
import yaml import yaml
from docforge.loaders import GriffeLoader, discover_module_paths from docforge.loaders import GriffeLoader, discover_module_paths
from docforge.nav import (
MkDocsNavEmitter,
build_wiki_nav,
load_nav_spec,
resolve_nav,
)
from docforge.renderers import MkDocsRenderer from docforge.renderers import MkDocsRenderer
from docforge.nav import load_nav_spec, resolve_nav, MkDocsNavEmitter
def generate_sources( def generate_sources(
@@ -12,6 +27,7 @@ def generate_sources(
docs_dir: Path, docs_dir: Path,
project_name: str | None = None, project_name: str | None = None,
module_is_source: bool | None = None, module_is_source: bool | None = None,
readme_dir: Path | None = None,
) -> None: ) -> None:
""" """
Generate MkDocs Markdown sources for a Python module. Generate MkDocs Markdown sources for a Python module.
@@ -21,13 +37,23 @@ def generate_sources(
use with MkDocs. use with MkDocs.
Args: 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. documentation generation.
docs_dir: Directory where the generated Markdown files will be written.
project_name: Optional override for the project name used in docs_dir (Path):
documentation metadata. Directory where the generated Markdown files will be written.
module_is_source: If True, treat the specified module directory as
the project root rather than a nested module. 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.
readme_dir (Optional[Path]):
Directory where the generated README.md should be written. If not
provided, defaults to the parent of ``docs_dir``.
""" """
loader = GriffeLoader() loader = GriffeLoader()
discovered_paths = discover_module_paths(module) discovered_paths = discover_module_paths(module)
@@ -44,6 +70,7 @@ def generate_sources(
project, project,
docs_dir, docs_dir,
module_is_source, module_is_source,
readme_dir,
) )
@@ -53,51 +80,220 @@ def generate_config(
template: Path | None, template: Path | None,
out: Path, out: Path,
site_name: str, site_name: str,
modes: Iterable[str] | None = None,
site_description: str | None = None,
site_author: str | None = None,
wiki_dir: Path | None = None,
) -> None: ) -> None:
""" """
Generate an ``mkdocs.yml`` configuration file. Generate an `mkdocs.yml` configuration file.
The configuration is created by combining a template configuration The configuration is created by combining a template configuration
with a navigation structure derived from the docforge navigation with a navigation structure derived from the docforge navigation
specification. specification (and, when a wiki directory is provided, from the wiki
file structure).
The ``docs_dir`` is always written relative to the MkDocs root and is
expected to be the shared documentation parent (for example ``docs``),
with generated sources nested under ``lib/`` or ``api/`` subdirectories
and hand-written wiki content under a ``wiki/`` subdirectory.
Args: Args:
docs_dir: Directory containing generated documentation Markdown files. docs_dir (Path):
nav_file: Path to the ``docforge.nav.yml`` navigation specification. Shared documentation root used as the MkDocs ``docs_dir``.
template: Optional path to a custom MkDocs configuration template.
If not provided, a built-in template will be used. nav_file (Path):
out: Destination path where the generated ``mkdocs.yml`` file Path to the `docforge.nav.yml` navigation specification.
will be written.
site_name: Display name for the generated documentation site. template (Optional[Path]):
Optional path to a fully custom MkDocs configuration template.
If not provided, built-in templates are merged; the provided
template replaces the built-in templates entirely.
out (Path):
Destination path where the generated `mkdocs.yml` file will be written.
site_name (str):
Display name for the generated documentation site.
modes (Optional[Iterable[str]]):
Documentation modes to enable. Each mode contributes its own
built-in template fragment (for example ``lib``, ``api``, or
``wiki``), merged on top of the shared ``mkdocs.common.yml``
template.
site_description (Optional[str]):
Optional site description written into the configuration.
site_author (Optional[str]):
Optional site author written into the configuration.
wiki_dir (Optional[Path]):
Optional path to a hand-written wiki directory (for example
``docs/wiki``). When provided, the site navigation is derived
from the wiki file structure and placed before the navigation
groups defined in ``nav_file``.
Raises: Raises:
click.FileError: If the navigation specification or template click.FileError:
file cannot be found. If the navigation specification, template, or wiki directory
cannot be found.
""" """
if not nav_file.exists(): if not nav_file.exists() and wiki_dir is None:
raise click.FileError(str(nav_file), hint="Nav spec not found") raise click.FileError(str(nav_file), hint="Nav spec not found")
spec = load_nav_spec(nav_file) nav_block: list[dict] = []
resolved = resolve_nav(spec, docs_dir) if nav_file.exists():
nav_block = MkDocsNavEmitter().emit(resolved) spec = load_nav_spec(nav_file)
resolved = resolve_nav(spec, docs_dir)
nav_block = MkDocsNavEmitter().emit(resolved)
else:
spec = None
# Load template if wiki_dir is not None:
if not wiki_dir.exists():
raise click.FileError(str(wiki_dir), hint="Wiki dir not found")
wiki_nav = build_wiki_nav(wiki_dir)
if wiki_nav:
nav_block = wiki_nav + [entry for entry in nav_block if "Home" not in entry]
data = _load_template(template, modes)
data["site_name"] = site_name
if site_description:
data["site_description"] = site_description
if site_author:
data["site_author"] = site_author
data["docs_dir"] = Path(os.path.relpath(docs_dir, out.parent)).as_posix()
data["nav"] = nav_block
if spec is not None and spec.icon:
theme = data.setdefault("theme", {})
if not isinstance(theme, dict):
theme = {}
theme["icon"] = spec.icon
data["theme"] = theme
out.write_text(yaml.safe_dump(data, sort_keys=False), encoding="utf-8")
def _load_template(
template: Path | None,
modes: Iterable[str] | None,
) -> dict:
"""
Load the MkDocs configuration template.
When a custom template path is provided, it is used as-is. Otherwise the
shared ``mkdocs.common.yml`` template is deep-merged with the fragments
contributed by each enabled mode (``lib`` or ``api``).
Args:
template (Optional[Path]):
Optional fully custom template that replaces the built-ins.
modes (Optional[Iterable[str]]):
Documentation modes whose template fragments should be merged.
Returns:
dict:
Merged MkDocs configuration mapping.
Raises:
click.FileError:
If a referenced template file cannot be found.
"""
if template is not None: if template is not None:
if not template.exists(): if not template.exists():
raise click.FileError(str(template), hint="Template not found") raise click.FileError(str(template), hint="Template not found")
data = yaml.safe_load(template.read_text(encoding="utf-8")) return yaml.safe_load(template.read_text(encoding="utf-8"))
else:
data: dict = {}
active_modes = list(modes) if modes else ["lib"]
parts = ["common", *active_modes]
seen: set[str] = set()
for part_name in parts:
if part_name in seen:
continue
seen.add(part_name)
text = ( text = (
resources.files("docforge.templates") resources.files("docforge.templates")
.joinpath("mkdocs.sample.yml") .joinpath(f"mkdocs.{part_name}.yml")
.read_text(encoding="utf-8") .read_text(encoding="utf-8")
) )
data = yaml.safe_load(text) part: dict = yaml.safe_load(text)
data = _deep_merge(data, part)
data["site_name"] = site_name return data
data["nav"] = nav_block
out.write_text(yaml.safe_dump(data, sort_keys=False), encoding="utf-8")
def _item_name(item: object) -> str:
"""
Return the identifying name of a list entry.
String entries identify as themselves; mapping entries identify by their
first key. This is used to deduplicate plugin and extension lists.
Args:
item: List entry, either a string or a single-key mapping.
Returns:
str:
The identifying name of the entry.
"""
if isinstance(item, dict):
return next(iter(item.keys()), "")
return str(item)
def _merge_list(base: list, added: list) -> list:
"""
Merge two lists, preserving order and dropping duplicates by name.
Args:
base: Existing list entries.
added: Entries to append when not already present.
Returns:
list:
Merged list with duplicates removed.
"""
result = list(base)
names = {_item_name(item) for item in result}
for item in added:
name = _item_name(item)
if name not in names:
result.append(item)
names.add(name)
return result
def _deep_merge(base: dict, part: dict) -> dict:
"""
Deep merge a template fragment into a base configuration.
Mappings are merged recursively, while lists are combined by
deduplicating entries by their identifying name. Non-container values in
the fragment override the base.
Args:
base: Configuration being built up.
part: Template fragment to merge into the base.
Returns:
dict:
The merged configuration.
"""
for key, value in part.items():
if isinstance(value, dict) and isinstance(base.get(key), dict):
base[key] = _deep_merge(base[key], value)
elif isinstance(value, list) and isinstance(base.get(key), list):
base[key] = _merge_list(base[key], value)
else:
base[key] = value
return base
def build(mkdocs_yml: Path) -> None: def build(mkdocs_yml: Path) -> None:
@@ -108,16 +304,18 @@ def build(mkdocs_yml: Path) -> None:
build command to generate the final static documentation site. build command to generate the final static documentation site.
Args: Args:
mkdocs_yml: Path to the ``mkdocs.yml`` configuration file. mkdocs_yml (Path):
Path to the `mkdocs.yml` configuration file.
Raises: Raises:
click.ClickException: If the configuration file does not exist. click.ClickException:
If the configuration file does not exist.
""" """
if not mkdocs_yml.exists(): if not mkdocs_yml.exists():
raise click.ClickException(f"mkdocs.yml not found: {mkdocs_yml}") raise click.ClickException(f"mkdocs.yml not found: {mkdocs_yml}")
from mkdocs.config import load_config
from mkdocs.commands.build import build as mkdocs_build from mkdocs.commands.build import build as mkdocs_build
from mkdocs.config import load_config
mkdocs_build(load_config(str(mkdocs_yml))) mkdocs_build(load_config(str(mkdocs_yml)))
@@ -130,13 +328,16 @@ def serve(mkdocs_yml: Path) -> None:
the site when changes are detected. the site when changes are detected.
Args: Args:
mkdocs_yml: Path to the ``mkdocs.yml`` configuration file. mkdocs_yml (Path):
Path to the `mkdocs.yml` configuration file.
Raises: Raises:
click.ClickException: If the configuration file does not exist. click.ClickException:
If the configuration file does not exist.
""" """
if not mkdocs_yml.exists(): if not mkdocs_yml.exists():
raise click.ClickException(f"mkdocs.yml not found: {mkdocs_yml}") raise click.ClickException(f"mkdocs.yml not found: {mkdocs_yml}")
from mkdocs.commands.serve import serve as mkdocs_serve from mkdocs.commands.serve import serve as mkdocs_serve
mkdocs_serve(config_file=str(mkdocs_yml)) mkdocs_serve(config_file=str(mkdocs_yml))

View File

@@ -1,3 +1,4 @@
from collections.abc import Iterable
from pathlib import Path from pathlib import Path
def generate_sources( def generate_sources(
@@ -5,7 +6,18 @@ def generate_sources(
docs_dir: Path, docs_dir: Path,
project_name: str | None = None, project_name: str | None = None,
module_is_source: bool | None = None, module_is_source: bool | None = None,
readme_dir: Path | None = None,
) -> None: ...
def generate_config(
docs_dir: Path,
nav_file: Path,
template: Path | None,
out: Path,
site_name: str,
modes: Iterable[str] | None = None,
site_description: str | None = None,
site_author: str | None = None,
wiki_dir: Path | None = None,
) -> None: ... ) -> None: ...
def generate_config(docs_dir: Path, nav_file: Path, template: Path | None, out: Path, site_name: str) -> None: ...
def build(mkdocs_yml: Path) -> None: ... def build(mkdocs_yml: Path) -> None: ...
def serve(mkdocs_yml: Path) -> None: ... def serve(mkdocs_yml: Path) -> None: ...

View File

@@ -1,13 +1,14 @@
""" """
# Summary
Loader layer for doc-forge. Loader layer for doc-forge.
The ``docforge.loaders`` package is responsible for discovering Python modules The `docforge.loaders` package is responsible for discovering Python modules
and extracting documentation data using static analysis. and extracting documentation data using static analysis.
--- ---
Overview # Overview
--------
This layer converts Python source code into an intermediate documentation This layer converts Python source code into an intermediate documentation
model used by doc-forge. It performs module discovery, introspection, and model used by doc-forge. It performs module discovery, introspection, and
@@ -17,9 +18,9 @@ Core capabilities include:
- **Module discovery** – Locate Python modules and packages within a project. - **Module discovery** – Locate Python modules and packages within a project.
- **Static introspection** – Parse docstrings, signatures, and object - **Static introspection** – Parse docstrings, signatures, and object
hierarchies using the ``griffe`` library without executing the code. hierarchies using the `griffe` library without executing the code.
- **Public API filtering** – Exclude private members (names prefixed with - **Public API filtering** – Exclude private members (names prefixed with
``_``) to produce clean public documentation structures. `_`) to produce clean public documentation structures.
--- ---
""" """

View File

@@ -1,24 +1,27 @@
""" """
# Summary
Utilities for loading and introspecting Python modules using Griffe. Utilities for loading and introspecting Python modules using Griffe.
This module provides the ``GriffeLoader`` class and helper utilities used to This module provides the `GriffeLoader` class and helper utilities used to
discover Python modules, introspect their structure, and convert the results discover Python modules, introspect their structure, and convert the results
into doc-forge documentation models. into doc-forge documentation models.
""" """
import logging import logging
from pathlib import Path from pathlib import Path
from typing import List, Optional
from griffe import ( from griffe import (
GriffeLoader as _GriffeLoader,
ModulesCollection,
LinesCollection,
Object,
AliasResolutionError, AliasResolutionError,
LinesCollection,
ModulesCollection,
Object,
)
from griffe import (
GriffeLoader as _GriffeLoader,
) )
from docforge.models import Module, Project, DocObject from docforge.models import DocObject, Module, Project
logger = logging.getLogger(__name__) logger = logging.getLogger(__name__)
@@ -26,29 +29,34 @@ logger = logging.getLogger(__name__)
def discover_module_paths( def discover_module_paths(
module_name: str, module_name: str,
project_root: Path | None = None, project_root: Path | None = None,
) -> List[str]: ) -> list[str]:
""" """
Discover Python modules within a package directory. Discover Python modules within a package directory.
The function scans the filesystem for ``.py`` files inside the specified The function scans the filesystem for `.py` files inside the specified
package and converts them into dotted module import paths. package and converts them into dotted module import paths.
Discovery rules: Discovery rules:
- Directories containing ``__init__.py`` are treated as packages. - Directories containing `__init__.py` are treated as packages.
- Each ``.py`` file is treated as a module. - Each `.py` file is treated as a module.
- Results are returned as dotted import paths. - Results are returned as dotted import paths.
Args: Args:
module_name: Top-level package name to discover modules from. module_name (str):
project_root: Root directory used to resolve module paths. If not Top-level package name to discover modules from.
provided, the current working directory is used.
project_root (Path, optional):
Root directory used to resolve module paths. If not provided, the
current working directory is used.
Returns: Returns:
A sorted list of unique dotted module import paths. List[str]:
A sorted list of unique dotted module import paths.
Raises: Raises:
FileNotFoundError: If the specified package directory does not exist. FileNotFoundError:
If the specified package directory does not exist.
""" """
if project_root is None: if project_root is None:
@@ -58,7 +66,7 @@ def discover_module_paths(
if not pkg_dir.exists(): if not pkg_dir.exists():
raise FileNotFoundError(f"Package not found: {pkg_dir}") raise FileNotFoundError(f"Package not found: {pkg_dir}")
module_paths: List[str] = [] module_paths: list[str] = []
for path in pkg_dir.rglob("*.py"): for path in pkg_dir.rglob("*.py"):
if path.name == "__init__.py": if path.name == "__init__.py":
@@ -78,8 +86,8 @@ class GriffeLoader:
Load Python modules using Griffe and convert them into doc-forge models. Load Python modules using Griffe and convert them into doc-forge models.
This loader uses the Griffe introspection engine to analyze Python source This loader uses the Griffe introspection engine to analyze Python source
code and transform the extracted information into ``Project``, ``Module``, code and transform the extracted information into `Project`, `Module`,
and ``DocObject`` instances used by doc-forge. and `DocObject` instances used by doc-forge.
""" """
def __init__(self) -> None: def __init__(self) -> None:
@@ -95,32 +103,39 @@ class GriffeLoader:
) )
def load_project( def load_project(
self, self,
module_paths: List[str], module_paths: list[str],
project_name: Optional[str] = None, project_name: str | None = None,
skip_import_errors: bool = None, skip_import_errors: bool = None,
) -> Project: ) -> Project:
""" """
Load multiple modules and assemble them into a Project model. Load multiple modules and assemble them into a Project model.
Each module path is introspected and converted into a ``Module`` Each module path is introspected and converted into a `Module`
instance. All modules are then aggregated into a single ``Project`` instance. All modules are then aggregated into a single `Project`
object. object.
Args: Args:
module_paths: List of dotted module import paths to load. module_paths (List[str]):
project_name: Optional override for the project name. Defaults List of dotted module import paths to load.
to the top-level name of the first module.
skip_import_errors: If True, modules that fail to load will be project_name (str, optional):
skipped instead of raising an error. Optional override for the project name. Defaults to the top-level
name of the first module.
skip_import_errors (bool, optional):
If True, modules that fail to load will be skipped instead of raising an error.
Returns: Returns:
A populated ``Project`` instance containing the loaded modules. Project:
A populated `Project` instance containing the loaded modules.
Raises: Raises:
ValueError: If no module paths are provided. ValueError:
ImportError: If a module fails to load and If no module paths are provided.
``skip_import_errors`` is False.
ImportError:
If a module fails to load and `skip_import_errors` is False.
""" """
if not module_paths: if not module_paths:
raise ValueError("At least one module path must be provided") raise ValueError("At least one module path must be provided")
@@ -148,13 +163,15 @@ class GriffeLoader:
Load and convert a single Python module. Load and convert a single Python module.
The module is introspected using Griffe and then transformed into The module is introspected using Griffe and then transformed into
a doc-forge ``Module`` model. a doc-forge `Module` model.
Args: Args:
path: Dotted import path of the module. path (str):
Dotted import path of the module.
Returns: Returns:
A populated ``Module`` instance. Module:
A populated `Module` instance.
""" """
self._loader.load(path) self._loader.load(path)
griffe_module = self._loader.modules_collection[path] griffe_module = self._loader.modules_collection[path]
@@ -170,13 +187,15 @@ class GriffeLoader:
Convert a Griffe module object into a doc-forge Module. Convert a Griffe module object into a doc-forge Module.
All public members of the module are recursively converted into All public members of the module are recursively converted into
``DocObject`` instances. `DocObject` instances.
Args: Args:
obj: Griffe object representing the module. obj (Object):
Griffe object representing the module.
Returns: Returns:
A populated ``Module`` model. Module:
A populated `Module` model.
""" """
module = Module( module = Module(
path=obj.path, path=obj.path,
@@ -200,10 +219,12 @@ class GriffeLoader:
recursively. recursively.
Args: Args:
obj: Griffe object representing a documented Python object. obj (Object):
Griffe object representing a documented Python object.
Returns: Returns:
A ``DocObject`` instance representing the converted object. DocObject:
A `DocObject` instance representing the converted object.
""" """
kind = obj.kind.value kind = obj.kind.value
signature = self._safe_signature(obj) signature = self._safe_signature(obj)
@@ -230,31 +251,34 @@ class GriffeLoader:
# Safe extractors # Safe extractors
# ------------------------- # -------------------------
def _safe_docstring(self, obj: Object) -> Optional[str]: def _safe_docstring(self, obj: Object) -> str | None:
""" """
Safely extract a docstring from a Griffe object. Safely extract a docstring from a Griffe object.
Args: Args:
obj: Griffe object to inspect. obj (Object):
Griffe object to inspect.
Returns: Returns:
The raw docstring text if available, otherwise ``None``. Optional[str]:
The raw docstring text if available, otherwise `None`.
""" """
try: try:
return obj.docstring.value if obj.docstring else None return obj.docstring.value if obj.docstring else None
except AliasResolutionError: except AliasResolutionError:
return None return None
def _safe_signature(self, obj: Object) -> Optional[str]: def _safe_signature(self, obj: Object) -> str | None:
""" """
Safely extract the signature of a Griffe object. Safely extract the signature of a Griffe object.
Args: Args:
obj: Griffe object to inspect. obj (Object):
Griffe object to inspect.
Returns: Returns:
String representation of the object's signature if available, Optional[str]:
otherwise ``None``. String representation of the object's signature if available, otherwise `None`.
""" """
try: try:
if hasattr(obj, "signature") and obj.signature: if hasattr(obj, "signature") and obj.signature:

View File

@@ -1,15 +1,11 @@
from typing import List, Optional
from pathlib import Path from pathlib import Path
from docforge.models import Module, Project from docforge.models import Module, Project
def discover_module_paths( def discover_module_paths(
module_name: str, module_name: str,
project_root: Path | None = None, project_root: Path | None = None,
) -> List[str]: ) -> list[str]: ...
...
class GriffeLoader: class GriffeLoader:
"""Griffe-based introspection loaders. """Griffe-based introspection loaders.
@@ -18,11 +14,10 @@ class GriffeLoader:
""" """
def __init__(self) -> None: ... def __init__(self) -> None: ...
def load_project( def load_project(
self, self,
module_paths: List[str], module_paths: list[str],
project_name: Optional[str] = ..., project_name: str | None = ...,
skip_import_errors: bool = ..., skip_import_errors: bool = ...,
) -> Project: ) -> Project:
"""Load a documentation project from Python modules.""" """Load a documentation project from Python modules."""

View File

@@ -1,13 +1,14 @@
""" """
# Summary
Model layer for doc-forge. Model layer for doc-forge.
The ``docforge.models`` package defines the core data structures used to The `docforge.models` package defines the core data structures used to
represent Python source code as a structured documentation model. represent Python source code as a structured documentation model.
--- ---
Overview # Overview
--------
The model layer forms the central intermediate representation used throughout The model layer forms the central intermediate representation used throughout
doc-forge. Python modules and objects discovered during introspection are doc-forge. Python modules and objects discovered during introspection are

View File

@@ -1,6 +1,6 @@
from .project import Project
from .module import Module from .module import Module
from .object import DocObject from .object import DocObject
from .project import Project
__all__ = [ __all__ = [
"Project", "Project",

View File

@@ -1,13 +1,15 @@
""" """
# Summary
Documentation model representing a Python module or package. Documentation model representing a Python module or package.
This module defines the ``Module`` class used in the doc-forge documentation This module defines the `Module` class used in the doc-forge documentation
model. A ``Module`` acts as a container for top-level documented objects model. A `Module` acts as a container for top-level documented objects
(classes, functions, variables, and other members) discovered during (classes, functions, variables, and other members) discovered during
introspection. introspection.
""" """
from typing import Dict, Iterable, Optional from collections.abc import Iterable
from docforge.models.object import DocObject from docforge.models.object import DocObject
@@ -16,40 +18,47 @@ class Module:
""" """
Representation of a documented Python module or package. Representation of a documented Python module or package.
A ``Module`` stores metadata about the module itself and maintains a A `Module` stores metadata about the module itself and maintains a
collection of top-level documentation objects discovered during collection of top-level documentation objects discovered during
introspection. introspection.
Attributes: Attributes:
path: Dotted import path of the module. path (str):
docstring: Module-level documentation string, if present. Dotted import path of the module.
members: Mapping of object names to their corresponding
``DocObject`` representations. docstring (Optional[str]):
Module-level documentation string, if present.
members (Dict[str, DocObject]):
Mapping of object names to their corresponding `DocObject` representations.
""" """
def __init__( def __init__(
self, self,
path: str, path: str,
docstring: Optional[str] = None, docstring: str | None = None,
) -> None: ) -> None:
""" """
Initialize a Module instance. Initialize a Module instance.
Args: Args:
path: Dotted import path identifying the module. path (str):
docstring: Module-level documentation text, if available. Dotted import path identifying the module.
docstring (Optional[str]):
Module-level documentation text, if available.
""" """
self.path = path self.path = path
self.docstring = docstring self.docstring = docstring
self.members: Dict[str, DocObject] = {} self.members: dict[str, DocObject] = {}
def add_object(self, obj: DocObject) -> None: def add_object(self, obj: DocObject) -> None:
""" """
Add a documented object to the module. Add a documented object to the module.
Args: Args:
obj: Documentation object to register as a top-level obj (DocObject):
member of the module. Documentation object to register as a top-level member of the module.
""" """
self.members[obj.name] = obj self.members[obj.name] = obj
@@ -58,13 +67,16 @@ class Module:
Retrieve a documented object by name. Retrieve a documented object by name.
Args: Args:
name: Name of the object to retrieve. name (str):
Name of the object to retrieve.
Returns: Returns:
The corresponding ``DocObject`` instance. DocObject:
The corresponding `DocObject` instance.
Raises: Raises:
KeyError: If no object with the given name exists. KeyError:
If no object with the given name exists.
""" """
return self.members[name] return self.members[name]
@@ -73,7 +85,7 @@ class Module:
Return all top-level documentation objects in the module. Return all top-level documentation objects in the module.
Returns: Returns:
An iterable of ``DocObject`` instances representing the Iterable[DocObject]:
module's public members. An iterable of `DocObject` instances representing the module's public members.
""" """
return self.members.values() return self.members.values()

View File

@@ -1,23 +1,19 @@
from typing import Dict, Iterable, Optional from collections.abc import Iterable
from docforge.models.object import DocObject from docforge.models.object import DocObject
class Module: class Module:
"""Represents a documented Python module.""" """Represents a documented Python module."""
path: str path: str
docstring: Optional[str] docstring: str | None
members: Dict[str, DocObject] members: dict[str, DocObject]
def __init__( def __init__(
self, self,
path: str, path: str,
docstring: Optional[str] = ..., docstring: str | None = ...,
) -> None: ... ) -> None: ...
def add_object(self, obj: DocObject) -> None: ... def add_object(self, obj: DocObject) -> None: ...
def get_object(self, name: str) -> DocObject: ... def get_object(self, name: str) -> DocObject: ...
def get_all_objects(self) -> Iterable[DocObject]: ... def get_all_objects(self) -> Iterable[DocObject]: ...

View File

@@ -1,31 +1,43 @@
""" """
# Summary
Documentation model representing individual Python objects. Documentation model representing individual Python objects.
This module defines the ``DocObject`` class, the fundamental recursive unit of This module defines the `DocObject` class, the fundamental recursive unit of
the doc-forge documentation model. Each ``DocObject`` represents a Python the doc-forge documentation model. Each `DocObject` represents a Python
entity such as a class, function, method, or attribute, and may contain nested entity such as a class, function, method, or attribute, and may contain nested
members that form a hierarchical documentation structure. members that form a hierarchical documentation structure.
""" """
from typing import Dict, Iterable, Optional from collections.abc import Iterable
class DocObject: class DocObject:
""" """
Representation of a documented Python object. Representation of a documented Python object.
A ``DocObject`` models a single Python entity discovered during A `DocObject` models a single Python entity discovered during
introspection. Objects may contain nested members, allowing the structure introspection. Objects may contain nested members, allowing the structure
of modules, classes, and other containers to be represented recursively. of modules, classes, and other containers to be represented recursively.
Attributes: Attributes:
name: Local name of the object. name (str):
kind: Type of object (for example ``class``, ``function``, Local name of the object.
``method``, or ``attribute``).
path: Fully qualified dotted path to the object. kind (str):
signature: Callable signature if the object represents a callable. Type of object (for example `class`, `function`, `method`, or `attribute`).
docstring: Raw docstring text extracted from the source code.
members: Mapping of member names to child ``DocObject`` instances. path (str):
Fully qualified dotted path to the object.
signature (Optional[str]):
Callable signature if the object represents a callable.
docstring (Optional[str]):
Raw docstring text extracted from the source code.
members (Dict[str, DocObject]):
Mapping of member names to child `DocObject` instances.
""" """
def __init__( def __init__(
@@ -33,25 +45,34 @@ class DocObject:
name: str, name: str,
kind: str, kind: str,
path: str, path: str,
signature: Optional[str] = None, signature: str | None = None,
docstring: Optional[str] = None, docstring: str | None = None,
) -> None: ) -> None:
""" """
Initialize a DocObject instance. Initialize a DocObject instance.
Args: Args:
name: Local name of the object. name (str):
kind: Object type identifier (for example ``class`` or ``function``). Local name of the object.
path: Fully qualified dotted path of the object.
signature: Callable signature if applicable. kind (str):
docstring: Documentation string associated with the object. Object type identifier (for example `class` or `function`).
path (str):
Fully qualified dotted path of the object.
signature (Optional[str]):
Callable signature if applicable.
docstring (Optional[str]):
Documentation string associated with the object.
""" """
self.name = name self.name = name
self.kind = kind self.kind = kind
self.path = path self.path = path
self.signature = signature self.signature = signature
self.docstring = docstring self.docstring = docstring
self.members: Dict[str, "DocObject"] = {} self.members: dict[str, DocObject] = {}
def add_member(self, obj: "DocObject") -> None: def add_member(self, obj: "DocObject") -> None:
""" """
@@ -70,13 +91,16 @@ class DocObject:
Retrieve a member object by name. Retrieve a member object by name.
Args: Args:
name: Name of the member to retrieve. name (str):
Name of the member to retrieve.
Returns: Returns:
The corresponding ``DocObject`` instance. DocObject:
The corresponding `DocObject` instance.
Raises: Raises:
KeyError: If the member does not exist. KeyError:
If the member does not exist.
""" """
return self.members[name] return self.members[name]
@@ -85,6 +109,7 @@ class DocObject:
Return all child members of the object. Return all child members of the object.
Returns: Returns:
An iterable of ``DocObject`` instances representing nested members. Iterable[DocObject]:
An iterable of `DocObject` instances representing nested members.
""" """
return self.members.values() return self.members.values()

View File

@@ -1,5 +1,4 @@
from typing import Dict, Iterable, Optional from collections.abc import Iterable
class DocObject: class DocObject:
"""Represents a documented Python object.""" """Represents a documented Python object."""
@@ -7,21 +6,18 @@ class DocObject:
name: str name: str
kind: str kind: str
path: str path: str
signature: Optional[str] signature: str | None
docstring: Optional[str] docstring: str | None
members: Dict[str, "DocObject"] members: dict[str, DocObject]
def __init__( def __init__(
self, self,
name: str, name: str,
kind: str, kind: str,
path: str, path: str,
signature: Optional[str] = ..., signature: str | None = ...,
docstring: Optional[str] = ..., docstring: str | None = ...,
) -> None: ... ) -> None: ...
def add_member(self, obj: DocObject) -> None: ...
def add_member(self, obj: "DocObject") -> None: ... def get_member(self, name: str) -> DocObject: ...
def get_all_members(self) -> Iterable[DocObject]: ...
def get_member(self, name: str) -> "DocObject": ...
def get_all_members(self) -> Iterable["DocObject"]: ...

View File

@@ -1,12 +1,14 @@
""" """
# Summary
Documentation model representing a project. Documentation model representing a project.
This module defines the ``Project`` class, the top-level container used by This module defines the `Project` class, the top-level container used by
doc-forge to represent a documented codebase. A ``Project`` aggregates multiple doc-forge to represent a documented codebase. A `Project` aggregates multiple
modules and provides access to them through a unified interface. modules and provides access to them through a unified interface.
""" """
from typing import Dict, Iterable from collections.abc import Iterable
from docforge.models.module import Module from docforge.models.module import Module
@@ -15,12 +17,15 @@ class Project:
""" """
Representation of a documentation project. Representation of a documentation project.
A ``Project`` serves as the root container for all modules discovered during A `Project` serves as the root container for all modules discovered during
introspection. Each module is stored by its dotted import path. introspection. Each module is stored by its dotted import path.
Attributes: Attributes:
name: Name of the project. name (str):
modules: Mapping of module paths to ``Module`` instances. Name of the project.
modules (Dict[str, Module]):
Mapping of module paths to `Module` instances.
""" """
def __init__(self, name: str) -> None: def __init__(self, name: str) -> None:
@@ -28,17 +33,19 @@ class Project:
Initialize a Project instance. Initialize a Project instance.
Args: Args:
name: Name used to identify the documentation project. name (str):
Name used to identify the documentation project.
""" """
self.name = name self.name = name
self.modules: Dict[str, Module] = {} self.modules: dict[str, Module] = {}
def add_module(self, module: Module) -> None: def add_module(self, module: Module) -> None:
""" """
Register a module in the project. Register a module in the project.
Args: Args:
module: Module instance to add to the project. module (Module):
Module instance to add to the project.
""" """
self.modules[module.path] = module self.modules[module.path] = module
@@ -47,13 +54,16 @@ class Project:
Retrieve a module by its dotted path. Retrieve a module by its dotted path.
Args: Args:
path: Fully qualified dotted module path (for example ``pkg.module``). path (str):
Fully qualified dotted module path (for example `pkg.module`).
Returns: Returns:
The corresponding ``Module`` instance. Module:
The corresponding `Module` instance.
Raises: Raises:
KeyError: If the module does not exist in the project. KeyError:
If the module does not exist in the project.
""" """
return self.modules[path] return self.modules[path]
@@ -62,7 +72,8 @@ class Project:
Return all modules contained in the project. Return all modules contained in the project.
Returns: Returns:
An iterable of ``Module`` instances. Iterable[Module]:
An iterable of `Module` instances.
""" """
return self.modules.values() return self.modules.values()
@@ -71,6 +82,7 @@ class Project:
Return the list of module import paths. Return the list of module import paths.
Returns: Returns:
A list containing the dotted paths of all modules in the project. list[str]:
A list containing the dotted paths of all modules in the project.
""" """
return list(self.modules.keys()) return list(self.modules.keys())

View File

@@ -1,20 +1,15 @@
from typing import Dict, Iterable from collections.abc import Iterable
from docforge.models.module import Module from docforge.models.module import Module
class Project: class Project:
"""Represents a documentation project.""" """Represents a documentation project."""
name: str name: str
modules: Dict[str, Module] modules: dict[str, Module]
def __init__(self, name: str) -> None: ... def __init__(self, name: str) -> None: ...
def add_module(self, module: Module) -> None: ... def add_module(self, module: Module) -> None: ...
def get_module(self, path: str) -> Module: ... def get_module(self, path: str) -> Module: ...
def get_all_modules(self) -> Iterable[Module]: ... def get_all_modules(self) -> Iterable[Module]: ...
def get_module_list(self) -> list[str]: ... def get_module_list(self) -> list[str]: ...

View File

@@ -26,11 +26,13 @@ independent of module hierarchy.
from .spec import NavSpec, load_nav_spec from .spec import NavSpec, load_nav_spec
from .resolver import ResolvedNav, resolve_nav from .resolver import ResolvedNav, resolve_nav
from .mkdocs import MkDocsNavEmitter from .mkdocs import MkDocsNavEmitter
from .wiki import build_wiki_nav
__all__ = [ __all__ = [
"NavSpec", "NavSpec",
"ResolvedNav", "ResolvedNav",
"MkDocsNavEmitter", "MkDocsNavEmitter",
"build_wiki_nav",
"resolve_nav", "resolve_nav",
"load_nav_spec", "load_nav_spec",
] ]

View File

@@ -1,11 +1,13 @@
from .spec import NavSpec, load_nav_spec
from .resolver import ResolvedNav, resolve_nav
from .mkdocs import MkDocsNavEmitter from .mkdocs import MkDocsNavEmitter
from .resolver import ResolvedNav, resolve_nav
from .spec import NavSpec, load_nav_spec
from .wiki import build_wiki_nav
__all__ = [ __all__ = [
"NavSpec", "NavSpec",
"ResolvedNav", "ResolvedNav",
"MkDocsNavEmitter", "MkDocsNavEmitter",
"build_wiki_nav",
"resolve_nav", "resolve_nav",
"load_nav_spec", "load_nav_spec",
] ]

View File

@@ -7,7 +7,7 @@ MkDocs ``nav`` configuration.
""" """
from pathlib import Path from pathlib import Path
from typing import List, Dict, Any from typing import Any
from docforge.nav.resolver import ResolvedNav from docforge.nav.resolver import ResolvedNav
@@ -20,7 +20,7 @@ class MkDocsNavEmitter:
list structure expected by the MkDocs ``nav`` configuration field. list structure expected by the MkDocs ``nav`` configuration field.
""" """
def emit(self, nav: ResolvedNav) -> List[Dict[str, Any]]: def emit(self, nav: ResolvedNav) -> list[dict[str, Any]]:
""" """
Generate a navigation structure for ``mkdocs.yml``. Generate a navigation structure for ``mkdocs.yml``.
@@ -33,7 +33,7 @@ class MkDocsNavEmitter:
Each dictionary maps a navigation label to a page or a list of Each dictionary maps a navigation label to a page or a list of
pages. pages.
""" """
result: List[Dict[str, Any]] = [] result: list[dict[str, Any]] = []
# Home entry (semantic path) # Home entry (semantic path)
if nav.home: if nav.home:
@@ -41,7 +41,7 @@ class MkDocsNavEmitter:
# Group entries # Group entries
for group, paths in nav.groups.items(): for group, paths in nav.groups.items():
entries: List[str] = [] entries: list[str] = []
for p in paths: for p in paths:
# Convert filesystem path back to docs-relative path # Convert filesystem path back to docs-relative path
rel_path = self._to_relative(p, nav._docs_root) rel_path = self._to_relative(p, nav._docs_root)
@@ -75,7 +75,7 @@ class MkDocsNavEmitter:
path_str = path.as_posix() path_str = path.as_posix()
docs_root_str = docs_root.as_posix() docs_root_str = docs_root.as_posix()
if path_str.startswith(docs_root_str + "/"): if path_str.startswith(docs_root_str + "/"):
return path_str[len(docs_root_str) + 1:] return path_str[len(docs_root_str) + 1 :]
# Fallback for other cases # Fallback for other cases
return path.as_posix().split("/docs/", 1)[-1] return path.as_posix().split("/docs/", 1)[-1]

View File

@@ -1,15 +1,14 @@
from typing import Dict, List, Any
from pathlib import Path from pathlib import Path
from typing import Any
from docforge.nav.resolver import ResolvedNav from docforge.nav.resolver import ResolvedNav
class MkDocsNavEmitter: class MkDocsNavEmitter:
""" """
Converts a ResolvedNav into MkDocs-compatible `nav` data. Converts a ResolvedNav into MkDocs-compatible `nav` data.
""" """
def emit(self, nav: ResolvedNav) -> List[Dict[str, Any]]: def emit(self, nav: ResolvedNav) -> list[dict[str, Any]]:
""" """
Emit a structure suitable for insertion into mkdocs.yml. Emit a structure suitable for insertion into mkdocs.yml.

View File

@@ -5,10 +5,9 @@ This module resolves a ``NavSpec`` against the filesystem by expanding glob
patterns and validating that referenced documentation files exist. patterns and validating that referenced documentation files exist.
""" """
from pathlib import Path
from typing import Dict, Iterable, List
import glob import glob
from collections.abc import Iterable
from pathlib import Path
from docforge.nav.spec import NavSpec from docforge.nav.spec import NavSpec
@@ -29,7 +28,7 @@ class ResolvedNav:
def __init__( def __init__(
self, self,
home: str | None, home: str | None,
groups: Dict[str, List[Path]], groups: dict[str, list[Path]],
docs_root: Path | None = None, docs_root: Path | None = None,
) -> None: ) -> None:
""" """
@@ -61,8 +60,7 @@ class ResolvedNav:
yield self._docs_root / self.home yield self._docs_root / self.home
for paths in self.groups.values(): for paths in self.groups.values():
for p in paths: yield from paths
yield p
def resolve_nav( def resolve_nav(
@@ -89,7 +87,7 @@ def resolve_nav(
if not docs_root.exists(): if not docs_root.exists():
raise FileNotFoundError(docs_root) raise FileNotFoundError(docs_root)
def resolve_pattern(pattern: str) -> List[Path]: def resolve_pattern(pattern: str) -> list[Path]:
""" """
Resolve a glob pattern relative to the documentation root. Resolve a glob pattern relative to the documentation root.
@@ -103,9 +101,7 @@ def resolve_nav(
FileNotFoundError: If the pattern does not match any files. FileNotFoundError: If the pattern does not match any files.
""" """
full = docs_root / pattern full = docs_root / pattern
matches = sorted( matches = sorted(Path(p) for p in glob.glob(str(full), recursive=True))
Path(p) for p in glob.glob(str(full), recursive=True)
)
if not matches: if not matches:
raise FileNotFoundError(pattern) raise FileNotFoundError(pattern)
@@ -121,10 +117,10 @@ def resolve_nav(
home = spec.home home = spec.home
# Resolve navigation groups # Resolve navigation groups
resolved_groups: Dict[str, List[Path]] = {} resolved_groups: dict[str, list[Path]] = {}
for group, patterns in spec.groups.items(): for group, patterns in spec.groups.items():
files: List[Path] = [] files: list[Path] = []
for pattern in patterns: for pattern in patterns:
files.extend(resolve_pattern(pattern)) files.extend(resolve_pattern(pattern))
resolved_groups[group] = files resolved_groups[group] = files

View File

@@ -1,9 +1,8 @@
from collections.abc import Iterable
from pathlib import Path from pathlib import Path
from typing import Dict, List, Iterable, Optional
from docforge.nav.spec import NavSpec from docforge.nav.spec import NavSpec
class ResolvedNav: class ResolvedNav:
""" """
Fully-resolved navigation tree. Fully-resolved navigation tree.
@@ -13,17 +12,16 @@ class ResolvedNav:
- Order is preserved - Order is preserved
""" """
home: Optional[str] home: str | None
groups: Dict[str, List[Path]] groups: dict[str, list[Path]]
_docs_root: Optional[Path] _docs_root: Path | None
def __init__( def __init__(
self, self,
home: str | None, home: str | None,
groups: Dict[str, List[Path]], groups: dict[str, list[Path]],
docs_root: Path | None = ..., docs_root: Path | None = ...,
) -> None: ... ) -> None: ...
def all_files(self) -> Iterable[Path]: def all_files(self) -> Iterable[Path]:
""" """
Return all resolved documentation files in nav order. Return all resolved documentation files in nav order.
@@ -33,7 +31,6 @@ class ResolvedNav:
""" """
... ...
def resolve_nav( def resolve_nav(
spec: NavSpec, spec: NavSpec,
docs_root: Path, docs_root: Path,

View File

@@ -7,7 +7,6 @@ structure defined by the user in the doc-forge navigation specification
""" """
from pathlib import Path from pathlib import Path
from typing import Dict, List, Optional
import yaml import yaml
@@ -24,12 +23,16 @@ class NavSpec:
``index.md``). ``index.md``).
groups: Mapping of navigation group titles to lists of file patterns groups: Mapping of navigation group titles to lists of file patterns
or glob expressions. or glob expressions.
icon: Optional mapping of theme icon entries (for example
``{"logo": "material/code-tags"}``) injected into the MkDocs
theme as ``theme.icon``.
""" """
def __init__( def __init__(
self, self,
home: Optional[str], home: str | None,
groups: Dict[str, List[str]], groups: dict[str, list[str]],
icon: dict[str, str] | None = None,
) -> None: ) -> None:
""" """
Initialize a NavSpec instance. Initialize a NavSpec instance.
@@ -38,9 +41,12 @@ class NavSpec:
home: Relative path to the home document. home: Relative path to the home document.
groups: Mapping of group names to lists of path patterns groups: Mapping of group names to lists of path patterns
(glob expressions). (glob expressions).
icon: Optional mapping of theme icon entries applied to the
generated MkDocs configuration.
""" """
self.home = home self.home = home
self.groups = groups self.groups = groups
self.icon = icon
@classmethod @classmethod
def load(cls, path: Path) -> "NavSpec": def load(cls, path: Path) -> "NavSpec":
@@ -68,6 +74,7 @@ class NavSpec:
home = data.get("home") home = data.get("home")
groups = data.get("groups", {}) groups = data.get("groups", {})
icon = data.get("icon")
if home is not None and not isinstance(home, str): if home is not None and not isinstance(home, str):
raise ValueError("home must be a string") raise ValueError("home must be a string")
@@ -83,9 +90,17 @@ class NavSpec:
): ):
raise ValueError(f"group '{key}' must be a list of strings") raise ValueError(f"group '{key}' must be a list of strings")
return cls(home=home, groups=groups) if icon is not None and (
not isinstance(icon, dict)
or not all(
isinstance(k, str) and isinstance(v, str) for k, v in icon.items()
)
):
raise ValueError("icon must be a mapping of strings")
def all_patterns(self) -> List[str]: return cls(home=home, groups=groups, icon=icon)
def all_patterns(self) -> list[str]:
""" """
Return all path patterns referenced by the specification. Return all path patterns referenced by the specification.
@@ -93,7 +108,7 @@ class NavSpec:
A list containing the home document (if defined) and all A list containing the home document (if defined) and all
group pattern entries. group pattern entries.
""" """
patterns: List[str] = [] patterns: list[str] = []
if self.home: if self.home:
patterns.append(self.home) patterns.append(self.home)
@@ -132,4 +147,5 @@ def load_nav_spec(path: Path) -> NavSpec:
return NavSpec( return NavSpec(
home=data.get("home"), home=data.get("home"),
groups=data.get("groups", {}), groups=data.get("groups", {}),
icon=data.get("icon"),
) )

View File

@@ -1,6 +1,4 @@
from pathlib import Path from pathlib import Path
from typing import Dict, List, Optional
class NavSpec: class NavSpec:
""" """
@@ -10,18 +8,16 @@ class NavSpec:
of filesystem structure or MkDocs specifics. of filesystem structure or MkDocs specifics.
""" """
home: Optional[str] home: str | None
groups: Dict[str, List[str]] groups: dict[str, list[str]]
def __init__( def __init__(
self, self,
home: Optional[str], home: str | None,
groups: Dict[str, List[str]], groups: dict[str, list[str]],
) -> None: ) -> None: ...
...
@classmethod @classmethod
def load(cls, path: Path) -> "NavSpec": def load(cls, path: Path) -> NavSpec:
""" """
Load and validate a nav specification from YAML. Load and validate a nav specification from YAML.
@@ -31,12 +27,11 @@ class NavSpec:
""" """
... ...
def all_patterns(self) -> List[str]: def all_patterns(self) -> list[str]:
""" """
Return all path patterns referenced by the spec Return all path patterns referenced by the spec
(including home and group entries). (including home and group entries).
""" """
... ...
def load_nav_spec(path: Path) -> NavSpec: ... def load_nav_spec(path: Path) -> NavSpec: ...

161
docforge/nav/wiki.py Normal file
View File

@@ -0,0 +1,161 @@
"""
# Summary
Wiki navigation derivation.
This module provides ``build_wiki_nav``, which derives an MkDocs-ready
navigation block from the file structure of a hand-written wiki directory
(typically ``docs/wiki``). wiki content is authored by hand and is never
modified by doc-forge; only the navigation layout is inferred.
# Notes
- ``index.md`` at the wiki root becomes the ``Home`` entry.
- Page labels are derived from filenames: numeric order prefixes such as
``01_`` or ``02-`` are stripped, separators are replaced with spaces, and
names are title-cased (``01_overview.md`` becomes ``Overview``).
- Subdirectories become nested navigation groups. A nested ``index.md`` is
rendered as the section root placed first inside the group.
- Only ``.md`` files are considered; hidden entries are ignored.
"""
import re
from pathlib import Path
from typing import Any
def build_wiki_nav(wiki_dir: Path) -> list[dict[str, Any]]:
"""
Derive an MkDocs navigation block from a wiki directory.
Returned paths are relative to the parent of ``wiki_dir`` and carry the
wiki directory name as their leading component (for example
``wiki/01_overview.md`` when the wiki lives at ``docs/wiki``). This makes
the result directly usable in an MkDocs ``nav`` block with
- ``index.md`` at the wiki root becomes the ``Home`` entry.
- Page labels are derived from filenames: numeric order prefixes such as
``01_`` or ``02-`` are stripped, separators are replaced with spaces, and
names are title-cased (``01_overview.md`` becomes ``Overview``).
- Subdirectories become nested navigation groups. A nested ``index.md`` is
rendered as the section root placed first inside the group.
- Only ``.md`` files are considered; hidden entries are ignored.
Args:
wiki_dir (Path):
Path to the hand-written wiki directory, for example ``docs/wiki``.
Returns:
List[Dict[str, Any]]:
Navigation entries compatible with the MkDocs ``nav`` configuration.
The list is empty if the wiki contains no Markdown files.
Raises:
FileNotFoundError:
If the wiki directory does not exist.
"""
if not wiki_dir.exists():
raise FileNotFoundError(wiki_dir)
root = wiki_dir.parent
def rel(path: Path) -> str:
try:
return path.relative_to(root).as_posix()
except ValueError:
return path.as_posix()
nav: list[dict[str, Any]] = []
if (wiki_dir / "index.md").exists():
nav.append({"Home": rel(wiki_dir / "index.md")})
nav.extend(_render_entries(wiki_dir, rel))
return nav
def _render_entries(base_dir: Path, rel) -> list[dict[str, Any]]:
"""
Render navigation entries for the children of a wiki directory.
Markdown pages become labeled entries, subdirectories containing
Markdown become nested groups, and a nested ``index.md`` is emitted
first as the section root.
Args:
base_dir (Path):
Directory whose children are rendered.
rel:
Callable converting a wiki file path into a docs-relative path.
Returns:
List[Dict[str, Any]]:
Navigation entries for ``base_dir`` in natural sort order.
"""
children = sorted(
(child for child in base_dir.iterdir() if not child.name.startswith(".")),
key=lambda child: _natural_key(child.name),
)
entries: list[dict[str, Any]] = []
for child in children:
if child.is_dir():
if not any(child.rglob("*.md")):
continue
group: list[dict[str, Any]] = []
nested_index = child / "index.md"
if nested_index.exists():
group.append({_prettify(child.name): rel(nested_index)})
group.extend(_render_entries(child, rel))
entries.append({_prettify(child.name): group})
elif child.suffix == ".md":
if child.name == "index.md":
continue
entries.append({_prettify(child.stem): rel(child)})
return entries
def _prettify(name: str) -> str:
"""
Convert a filename or directory name into a navigation label.
Numeric order prefixes (``01_``, ``02-``, ``03.``) are stripped,
separators are replaced with spaces, and the result is title-cased.
Args:
name (str):
Filename stem or directory name to prettify.
Returns:
str:
Title-cased navigation label.
"""
name = re.sub(r"^\d+[_\-. ]?", "", name)
name = re.sub(r"[_-]+", " ", name).strip()
return name.title()
def _natural_key(name: str) -> list[object]:
"""
Build a natural sort key from a filename.
The key splits ``name`` into alternating non-digit and digit parts so
that numeric prefixes sort numerically (``02`` before ``10``).
Args:
name (str):
Filename or directory name to key.
Returns:
List[object]:
Mixed list of lowercased strings and integers used for sorting.
"""
return [
int(part) if part.isdigit() else part.lower()
for part in re.split(r"(\d+)", name)
]

15
docforge/nav/wiki.pyi Normal file
View File

@@ -0,0 +1,15 @@
from pathlib import Path
from typing import Any
def build_wiki_nav(wiki_dir: Path) -> list[dict[str, Any]]:
"""
Derive an MkDocs navigation block from a wiki directory.
Returns:
Wiki navigation entries compatible with the MkDocs
`nav` configuration.
Raises:
FileNotFoundError: if the wiki directory does not exist
"""
...

0
docforge/py.typed Normal file
View File

View File

@@ -1,13 +1,14 @@
""" """
# Summary
Renderers layer for doc-forge. Renderers layer for doc-forge.
The ``docforge.renderers`` package transforms the internal documentation The `docforge.renderers` package transforms the internal documentation
models into files formatted for specific documentation systems. models into files formatted for specific documentation systems.
--- ---
Overview # Overview
--------
Renderers consume the doc-forge project model and generate output suitable Renderers consume the doc-forge project model and generate output suitable
for documentation tools or machine interfaces. for documentation tools or machine interfaces.
@@ -15,18 +16,17 @@ for documentation tools or machine interfaces.
Current implementations: Current implementations:
- **MkDocsRenderer** – Produces Markdown files compatible with MkDocs and - **MkDocsRenderer** – Produces Markdown files compatible with MkDocs and
the ``mkdocstrings`` plugin. It automatically handles package hierarchy the `mkdocstrings` plugin. It automatically handles package hierarchy
and generates ``index.md`` files for packages. and generates `index.md` files for packages.
- **MCPRenderer** – Emits structured JSON resources designed for consumption - **MCPRenderer** – Emits structured JSON resources designed for consumption
by Model Context Protocol (MCP) clients. by Model Context Protocol (MCP) clients.
--- ---
Extending # Extending
---------
New renderers can be added by implementing the ``DocRenderer`` protocol New renderers can be added by implementing the `DocRenderer` protocol
defined in ``docforge.renderers.base``. defined in `docforge.renderers.base`.
--- ---
""" """

View File

@@ -1,5 +1,5 @@
from .mkdocs_renderer import MkDocsRenderer
from .mcp_renderer import MCPRenderer from .mcp_renderer import MCPRenderer
from .mkdocs_renderer import MkDocsRenderer
__all__ = [ __all__ = [
"MkDocsRenderer", "MkDocsRenderer",

View File

@@ -1,9 +1,11 @@
""" """
# Summary
Renderer base interfaces and configuration models. Renderer base interfaces and configuration models.
This module defines the base protocol and configuration container used by This module defines the base protocol and configuration container used by
doc-forge renderers. Concrete renderer implementations should implement the doc-forge renderers. Concrete renderer implementations should implement the
``DocRenderer`` protocol. `DocRenderer` protocol.
""" """
from pathlib import Path from pathlib import Path
@@ -16,12 +18,15 @@ class RendererConfig:
""" """
Configuration container for documentation renderers. Configuration container for documentation renderers.
A ``RendererConfig`` instance groups together the project model and the A `RendererConfig` instance groups together the project model and the
output directory used during rendering. output directory used during rendering.
Attributes: Attributes:
out_dir: Directory where generated documentation files will be written. out_dir (Path):
project: Documentation project model to be rendered. Directory where generated documentation files will be written.
project (Project):
Documentation project model to be rendered.
""" """
def __init__(self, out_dir: Path, project: Project) -> None: def __init__(self, out_dir: Path, project: Project) -> None:
@@ -29,8 +34,11 @@ class RendererConfig:
Initialize a RendererConfig instance. Initialize a RendererConfig instance.
Args: Args:
out_dir: Target directory where documentation files should be written. out_dir (Path):
project: Introspected project model to render. Target directory where documentation files should be written.
project (Project):
Introspected project model to render.
""" """
self.out_dir = out_dir self.out_dir = out_dir
self.project = project self.project = project
@@ -41,7 +49,7 @@ class DocRenderer(Protocol):
Protocol defining the interface for documentation renderers. Protocol defining the interface for documentation renderers.
Implementations of this protocol are responsible for transforming a Implementations of this protocol are responsible for transforming a
``Project`` model into renderer-specific documentation sources. `Project` model into renderer-specific documentation sources.
""" """
name: str name: str
@@ -55,8 +63,10 @@ class DocRenderer(Protocol):
Generate renderer-specific documentation sources. Generate renderer-specific documentation sources.
Args: Args:
project: Project model containing modules and documentation objects. project (Project):
out_dir: Directory where generated documentation sources Project model containing modules and documentation objects.
should be written.
out_dir (Path):
Directory where generated documentation sources should be written.
""" """
... ...

View File

@@ -3,7 +3,6 @@ from typing import Protocol
from docforge.models import Project from docforge.models import Project
class RendererConfig: class RendererConfig:
"""Renderer configuration container.""" """Renderer configuration container."""
@@ -12,7 +11,6 @@ class RendererConfig:
def __init__(self, out_dir: Path, project: Project) -> None: ... def __init__(self, out_dir: Path, project: Project) -> None: ...
class DocRenderer(Protocol): class DocRenderer(Protocol):
"""Renderer interface.""" """Renderer interface."""

View File

@@ -1,8 +1,16 @@
"""
# Summary
MCP renderer implementation.
This module defines the `MCPRenderer` class, which generates documentation
resources compatible with the Model Context Protocol (MCP).
"""
import json import json
from pathlib import Path from pathlib import Path
from typing import Dict, List
from docforge.models import Project, Module, DocObject from docforge.models import DocObject, Module, Project
class MCPRenderer: class MCPRenderer:
@@ -21,24 +29,29 @@ class MCPRenderer:
Generate MCP documentation resources for a project. Generate MCP documentation resources for a project.
The renderer serializes each module into a JSON resource and produces The renderer serializes each module into a JSON resource and produces
supporting metadata files such as ``nav.json`` and ``index.json``. supporting metadata files such as `nav.json` and `index.json`.
Args: Args:
project: Documentation project model to render. project (Project):
out_dir: Directory where MCP resources will be written. Documentation project model to render.
out_dir (Path):
Directory where MCP resources will be written.
""" """
modules_dir = out_dir / "modules" modules_dir = out_dir / "modules"
modules_dir.mkdir(parents=True, exist_ok=True) modules_dir.mkdir(parents=True, exist_ok=True)
nav: List[Dict[str, str]] = [] nav: list[dict[str, str]] = []
for module in project.get_all_modules(): for module in project.get_all_modules():
self._write_module(module, modules_dir) self._write_module(module, modules_dir)
nav.append({ nav.append(
"module": module.path, {
"resource": f"doc://modules/{module.path}", "module": module.path,
}) "resource": f"doc://modules/{module.path}",
}
)
# Write nav.json # Write nav.json
(out_dir / "nav.json").write_text( (out_dir / "nav.json").write_text(
@@ -64,8 +77,11 @@ class MCPRenderer:
Serialize a module into an MCP resource file. Serialize a module into an MCP resource file.
Args: Args:
module: Module instance to serialize. module (Module):
modules_dir: Directory where module JSON files are stored. Module instance to serialize.
modules_dir (Path):
Directory where module JSON files are stored.
""" """
payload = { payload = {
"module": module.path, "module": module.path,
@@ -76,17 +92,19 @@ class MCPRenderer:
out.parent.mkdir(parents=True, exist_ok=True) out.parent.mkdir(parents=True, exist_ok=True)
out.write_text(self._json(payload), encoding="utf-8") out.write_text(self._json(payload), encoding="utf-8")
def _render_module(self, module: Module) -> Dict: def _render_module(self, module: Module) -> dict:
""" """
Convert a Module model into MCP-compatible structured data. Convert a Module model into MCP-compatible structured data.
Args: Args:
module: Module instance to convert. module (Module):
Module instance to convert.
Returns: Returns:
Dictionary representing the module and its documented objects. Dict:
Dictionary representing the module and its documented objects.
""" """
data: Dict = { data: dict = {
"path": module.path, "path": module.path,
"docstring": module.docstring, "docstring": module.docstring,
"objects": {}, "objects": {},
@@ -97,17 +115,19 @@ class MCPRenderer:
return data return data
def _render_object(self, obj: DocObject) -> Dict: def _render_object(self, obj: DocObject) -> dict:
""" """
Recursively convert a DocObject into structured MCP data. Recursively convert a DocObject into structured MCP data.
Args: Args:
obj: Documentation object to convert. obj (DocObject):
Documentation object to convert.
Returns: Returns:
Dictionary describing the object and any nested members. Dict:
Dictionary describing the object and any nested members.
""" """
data: Dict = { data: dict = {
"name": obj.name, "name": obj.name,
"kind": obj.kind, "kind": obj.kind,
"path": obj.path, "path": obj.path,
@@ -118,21 +138,22 @@ class MCPRenderer:
members = list(obj.get_all_members()) members = list(obj.get_all_members())
if members: if members:
data["members"] = { data["members"] = {
member.name: self._render_object(member) member.name: self._render_object(member) for member in members
for member in members
} }
return data return data
@staticmethod @staticmethod
def _json(data: Dict) -> str: def _json(data: dict) -> str:
""" """
Serialize data to formatted JSON. Serialize data to formatted JSON.
Args: Args:
data: Dictionary to serialize. data (Dict):
Dictionary to serialize.
Returns: Returns:
JSON string formatted with indentation and UTF-8 compatibility. str:
JSON string formatted with indentation and UTF-8 compatibility.
""" """
return json.dumps(data, indent=2, ensure_ascii=False) return json.dumps(data, indent=2, ensure_ascii=False)

View File

@@ -1,8 +1,7 @@
from pathlib import Path from pathlib import Path
from typing import Dict, List from typing import Any
from docforge.models import Project, Module, DocObject
from docforge.models import DocObject, Module, Project
class MCPRenderer: class MCPRenderer:
"""Renderer that emits MCP-native JSON resources from docforge models.""" """Renderer that emits MCP-native JSON resources from docforge models."""
@@ -15,12 +14,12 @@ class MCPRenderer:
def _write_module(self, module: Module, modules_dir: Path) -> None: def _write_module(self, module: Module, modules_dir: Path) -> None:
"""Serialize a module into an MCP JSON resource.""" """Serialize a module into an MCP JSON resource."""
def _render_module(self, module: Module) -> Dict: def _render_module(self, module: Module) -> dict[str, Any]:
"""Render a Module into MCP-friendly structured data.""" """Render a Module into MCP-friendly structured data."""
def _render_object(self, obj: DocObject) -> Dict: def _render_object(self, obj: DocObject) -> dict[str, Any]:
"""Recursively render a DocObject into structured MCP data.""" """Recursively render a DocObject into structured MCP data."""
@staticmethod @staticmethod
def _json(data: Dict) -> str: def _json(data: dict[str, Any]) -> str:
"""Serialize structured data to formatted JSON.""" """Serialize structured data to formatted JSON."""

View File

@@ -1,20 +1,23 @@
""" """
# Summary
MkDocs renderer implementation. MkDocs renderer implementation.
This module defines the ``MkDocsRenderer`` class, which generates Markdown This module defines the `MkDocsRenderer` class, which generates Markdown
documentation sources compatible with MkDocs Material and the mkdocstrings documentation sources compatible with MkDocs Material and the mkdocstrings
plugin. plugin.
The renderer ensures a consistent documentation structure by: The renderer ensures a consistent documentation structure by:
- Creating a root ``index.md`` if one does not exist - Creating a root `index.md` if one does not exist
- Generating package index pages automatically - Generating package index pages automatically
- Linking child modules within parent package pages - Linking child modules within parent package pages
- Optionally generating ``README.md`` from the root package docstring - Optionally generating `README.md` from the root package docstring
""" """
from pathlib import Path from pathlib import Path
from docforge.models import Project, Module
from docforge.models import Module, Project
class MkDocsRenderer: class MkDocsRenderer:
@@ -45,10 +48,15 @@ class MkDocsRenderer:
specified output directory. specified output directory.
Args: Args:
project: Project model containing modules to document. project (Project):
out_dir: Directory where generated Markdown files will be written. Project model containing modules to document.
module_is_source: If True, treat the specified module as the
documentation root rather than nesting it inside a folder. out_dir (Path):
Directory where generated Markdown files will be written.
module_is_source (bool, optional):
If True, treat the specified module as the documentation root
rather than nesting it inside a folder.
""" """
out_dir.mkdir(parents=True, exist_ok=True) out_dir.mkdir(parents=True, exist_ok=True)
self._ensure_root_index(project, out_dir) self._ensure_root_index(project, out_dir)
@@ -58,8 +66,7 @@ class MkDocsRenderer:
# Detect packages (modules with children) # Detect packages (modules with children)
packages = { packages = {
p for p in paths p for p in paths if any(other.startswith(p + ".") for other in paths)
if any(other.startswith(p + ".") for other in paths)
} }
for module in modules: for module in modules:
@@ -75,28 +82,38 @@ class MkDocsRenderer:
project: Project, project: Project,
docs_dir: Path, docs_dir: Path,
module_is_source: bool | None = None, module_is_source: bool | None = None,
readme_dir: Path | None = None,
) -> None: ) -> None:
""" """
Generate a ``README.md`` file from the root module docstring. Generate a `README.md` file from the root module docstring.
Behavior: Behavior:
- If ``module_is_source`` is True, ``README.md`` is written to the - If `module_is_source` is True, `README.md` is written to the project
project root directory. root directory.
- If False, README generation is currently not implemented. - If False, README generation is currently not implemented.
Args: Args:
project: Project model containing documentation metadata. project (Project):
docs_dir: Directory containing generated documentation sources. Project model containing documentation metadata.
module_is_source: Whether the module is treated as the project
source root. docs_dir (Path):
Directory containing generated documentation sources.
module_is_source (Optional[bool]):
Whether the module is treated as the project source root.
readme_dir (Optional[Path]):
Directory where the generated README.md should be written.
Defaults to the parent of `docs_dir`.
""" """
if not module_is_source: if not module_is_source:
# Future: support README generation per module # Future: support README generation per module
return return
readme_path = docs_dir.parent / "README.md" readme_root = readme_dir if readme_dir is not None else docs_dir.parent
readme_path = readme_root / "README.md"
root_module = None root_module = None
for module in project.get_all_modules(): for module in project.get_all_modules():
@@ -116,12 +133,12 @@ class MkDocsRenderer:
str(root_module.docstring), str(root_module.docstring),
) )
content = ( content = f"# {project.name}\n\n" f"{doc.strip()}\n"
f"# {project.name}\n\n"
f"{doc.strip()}\n"
)
if not readme_path.exists() or readme_path.read_text(encoding="utf-8") != content: if (
not readme_path.exists()
or readme_path.read_text(encoding="utf-8") != content
):
readme_path.write_text( readme_path.write_text(
content, content,
encoding="utf-8", encoding="utf-8",
@@ -136,10 +153,12 @@ class MkDocsRenderer:
Locate the root module corresponding to the project name. Locate the root module corresponding to the project name.
Args: Args:
project: Project model to inspect. project (Project):
Project model to inspect.
Returns: Returns:
The root ``Module`` if found, otherwise ``None``. Optional[Module]:
The root `Module` if found, otherwise `None`.
""" """
for module in project.get_all_modules(): for module in project.get_all_modules():
if module.path == project.name: if module.path == project.name:
@@ -156,16 +175,22 @@ class MkDocsRenderer:
""" """
Write documentation for a single module. Write documentation for a single module.
Package modules are rendered as ``index.md`` files inside their Package modules are rendered as `index.md` files inside their
corresponding directories, while leaf modules are written as corresponding directories, while leaf modules are written as
standalone Markdown pages. standalone Markdown pages.
Args: Args:
module: Module to render. module (Module):
packages: Set of module paths identified as packages. Module to render.
out_dir: Base directory for generated documentation files.
module_is_source: Whether the module acts as the documentation packages (set[str]):
root directory. Set of module paths identified as packages.
out_dir (Path):
Base directory for generated documentation files.
module_is_source (bool, optional):
Whether the module acts as the documentation root directory.
""" """
parts = module.path.split(".") parts = module.path.split(".")
@@ -202,16 +227,17 @@ class MkDocsRenderer:
Generate Markdown content for a module documentation page. Generate Markdown content for a module documentation page.
Args: Args:
title: Page title displayed in the documentation. title (str):
module_path: Dotted import path of the module. Page title displayed in the documentation.
module_path (str):
Dotted import path of the module.
Returns: Returns:
Markdown source containing a mkdocstrings directive. str:
Markdown source containing a mkdocstrings directive.
""" """
return ( return f"# {title}\n\n" f"::: {module_path}\n"
f"# {title}\n\n"
f"::: {module_path}\n"
)
def _ensure_root_index( def _ensure_root_index(
self, self,
@@ -219,18 +245,20 @@ class MkDocsRenderer:
out_dir: Path, out_dir: Path,
) -> None: ) -> None:
""" """
Ensure that the root ``index.md`` page exists. Ensure that the root `index.md` page exists.
Args: Args:
project: Project model used for the page title. project (Project):
out_dir: Documentation output directory. Project model used for the page title.
out_dir (Path):
Documentation output directory.
""" """
root_index = out_dir / "index.md" root_index = out_dir / "index.md"
if not root_index.exists(): if not root_index.exists():
root_index.write_text( root_index.write_text(
f"# {project.name}\n\n" f"# {project.name}\n\n" "## Modules\n\n",
"## Modules\n\n",
encoding="utf-8", encoding="utf-8",
) )
@@ -246,10 +274,17 @@ class MkDocsRenderer:
child modules. child modules.
Args: Args:
parts: Module path components. parts (list[str]):
out_dir: Documentation output directory. Module path components.
link_target: Link target used in the parent index.
title: Display title for the link. out_dir (Path):
Documentation output directory.
link_target (str):
Link target used in the parent index.
title (str):
Display title for the link.
""" """
if len(parts) == 1: if len(parts) == 1:
parent_index = out_dir / "index.md" parent_index = out_dir / "index.md"

View File

@@ -1,6 +1,6 @@
from pathlib import Path from pathlib import Path
from docforge.models import Project, Module
from docforge.models import Module, Project
class MkDocsRenderer: class MkDocsRenderer:
name: str name: str
@@ -11,14 +11,12 @@ class MkDocsRenderer:
out_dir: Path, out_dir: Path,
module_is_source: bool | None = None, module_is_source: bool | None = None,
) -> None: ... ) -> None: ...
def generate_readme( def generate_readme(
self, self,
project: Project, project: Project,
docs_dir: Path, docs_dir: Path,
module_is_source: bool | None = None, module_is_source: bool | None = None,
) -> None: ) -> None: ...
def _write_module( def _write_module(
self, self,
module: Module, module: Module,
@@ -26,9 +24,8 @@ class MkDocsRenderer:
out_dir: Path, out_dir: Path,
module_is_source: bool | None = None, module_is_source: bool | None = None,
) -> None: ... ) -> None: ...
def _render_markdown(self, title: str, module_path: str) -> str: ... def _render_markdown(self, title: str, module_path: str) -> str: ...
def _ensure_root_index(self, project: Project, out_dir: Path) -> None: ...
def _ensure_root_index(self, project, out_dir) -> None: ... def _ensure_parent_index(
self, parts: list[str], out_dir: Path, link_target: str, title: str
def _ensure_parent_index(self, parts, out_dir, link_target, title) -> None: ... ) -> None: ...

View File

@@ -1,4 +1,6 @@
""" """
# Summary
Server layer for doc-forge. Server layer for doc-forge.
This module exposes server implementations used to provide live access This module exposes server implementations used to provide live access

View File

@@ -1,3 +1,12 @@
"""
# Summary
MCP server implementation.
This module defines the `MCPServer` class, which serves pre-generated
documentation bundles through the Model Context Protocol (MCP).
"""
from __future__ import annotations from __future__ import annotations
import json import json
@@ -20,10 +29,12 @@ class MCPServer:
Initialize the MCP server. Initialize the MCP server.
Args: Args:
mcp_root: Directory containing the generated MCP documentation mcp_root (Path):
bundle (for example ``index.json``, ``nav.json``, and Directory containing the generated MCP documentation bundle
``modules/``). (for example `index.json`, `nav.json`, and `modules/`).
name: Identifier used for the MCP server instance.
name (str):
Identifier used for the MCP server instance.
""" """
self.mcp_root = mcp_root self.mcp_root = mcp_root
self.app = FastMCP(name) self.app = FastMCP(name)
@@ -43,11 +54,13 @@ class MCPServer:
instead of raising an exception. instead of raising an exception.
Args: Args:
path: Path to the JSON file to read. path (Path):
Path to the JSON file to read.
Returns: Returns:
Parsed JSON data if the file exists, otherwise an error dictionary Any:
describing the missing resource. Parsed JSON data if the file exists, otherwise an error dictionary
describing the missing resource.
""" """
if not path.exists(): if not path.exists():
return { return {
@@ -68,9 +81,9 @@ class MCPServer:
The server exposes documentation resources through the following The server exposes documentation resources through the following
endpoints: endpoints:
- ``docs://index`` – Project metadata - `docs://index` – Project metadata
- ``docs://nav`` – Navigation structure - `docs://nav` – Navigation structure
- ``docs://modules/{module}`` – Individual module documentation - `docs://modules/{module}` – Individual module documentation
""" """
@self.app.resource("docs://index") @self.app.resource("docs://index")
@@ -83,9 +96,7 @@ class MCPServer:
@self.app.resource("docs://modules/{module}") @self.app.resource("docs://modules/{module}")
def module(module: str): def module(module: str):
return self._read_json( return self._read_json(self.mcp_root / "modules" / f"{module}.json")
self.mcp_root / "modules" / f"{module}.json"
)
# ------------------------------------------------------------------ # ------------------------------------------------------------------
# MCP tools # MCP tools
@@ -116,7 +127,8 @@ class MCPServer:
Start the MCP server. Start the MCP server.
Args: Args:
transport: Transport mechanism used by the MCP server. Supported transport (Literal["stdio", "sse", "streamable-http"]):
options include ``stdio``, ``sse``, and ``streamable-http``. Transport mechanism used by the MCP server. Supported options
include `stdio`, `sse`, and `streamable-http`.
""" """
self.app.run(transport=transport) self.app.run(transport=transport)

View File

@@ -1,9 +1,8 @@
from pathlib import Path from pathlib import Path
from typing import Literal, Any from typing import Any, Literal
from mcp.server.fastmcp import FastMCP from mcp.server.fastmcp import FastMCP
class MCPServer: class MCPServer:
"""MCP server for serving documentation.""" """MCP server for serving documentation."""
@@ -11,12 +10,8 @@ class MCPServer:
app: FastMCP app: FastMCP
def __init__(self, mcp_root: Path, name: str) -> None: ... def __init__(self, mcp_root: Path, name: str) -> None: ...
def _read_json(self, path: Path) -> Any: ... def _read_json(self, path: Path) -> Any: ...
def _register_resources(self) -> None: ... def _register_resources(self) -> None: ...
def _register_tools(self) -> None: ... def _register_tools(self) -> None: ...
def run(self, transport: Literal["stdio", "sse", "streamable-http"] = ...) -> None: def run(self, transport: Literal["stdio", "sse", "streamable-http"] = ...) -> None:
"""Start the MCP server.""" """Start the MCP server."""

View File

@@ -0,0 +1,16 @@
theme:
features:
- toc.integrate
- header.autohide
- announce.dismiss
- footer.social
- content.code.select
- content.code.line_numbers
- content.tooltips
plugins:
- search
- swagger-ui-tag
- neoteroi.mkdocsoad:
use_pymdownx: true

View File

@@ -29,26 +29,6 @@ theme:
- search.share - search.share
- search.suggest - search.suggest
plugins:
- search
- mkdocstrings:
handlers:
python:
paths: ["."]
options:
docstring_style: google
show_source: false
show_signature_annotations: true
separate_signature: true
merge_init_into_class: true
inherited_members: true
annotations_path: brief
show_root_heading: true
group_by_category: true
show_category_heading: true
show_object_full_path: false
show_symbol_type_heading: true
markdown_extensions: markdown_extensions:
- pymdownx.superfences - pymdownx.superfences
- pymdownx.inlinehilite - pymdownx.inlinehilite
@@ -57,7 +37,6 @@ markdown_extensions:
- admonition - admonition
- pymdownx.details - pymdownx.details
- pymdownx.superfences
- pymdownx.highlight: - pymdownx.highlight:
linenums: true linenums: true
anchor_linenums: true anchor_linenums: true
@@ -76,3 +55,6 @@ markdown_extensions:
- pymdownx.caret - pymdownx.caret
- pymdownx.tilde - pymdownx.tilde
- pymdownx.mark - pymdownx.mark
extra_css:
- https://unpkg.com/dracula-prism/dist/css/dracula-prism.css

View File

@@ -0,0 +1,19 @@
plugins:
- search
- mkdocstrings:
handlers:
python:
paths: ["."]
options:
docstring_style: google
show_source: false
show_signature_annotations: true
separate_signature: true
merge_init_into_class: true
inherited_members: true
annotations_path: brief
show_root_heading: true
group_by_category: true
show_category_heading: true
show_object_full_path: false
show_symbol_type_heading: true

View File

@@ -0,0 +1,2 @@
plugins:
- search

View File

@@ -0,0 +1,3 @@
# Api Utils
::: docforge.cli.api_utils

View File

@@ -0,0 +1,3 @@
# Api Utils
::: docforge.cli.api_utils

View File

@@ -0,0 +1,3 @@
# Commands
::: docforge.cli.commands

View File

@@ -0,0 +1,8 @@
# Cli
::: docforge.cli
- [Api Utils](api_utils.md)
- [Commands](commands.md)
- [Main](main.md)
- [Mcp Utils](mcp_utils.md)
- [Mkdocs Utils](mkdocs_utils.md)

View File

@@ -0,0 +1,3 @@
# Main
::: docforge.cli.main

View File

@@ -0,0 +1,3 @@
# Mcp Utils
::: docforge.cli.mcp_utils

View File

@@ -0,0 +1,3 @@
# Mkdocs Utils
::: docforge.cli.mkdocs_utils

View File

@@ -0,0 +1,9 @@
# Docforge
::: docforge
- [Cli](cli/)
- [Loaders](loaders/)
- [Models](models/)
- [Nav](nav/)
- [Renderers](renderers/)
- [Servers](servers/)

View File

@@ -0,0 +1,4 @@
# Loaders
::: docforge.loaders
- [Griffe Loader](griffe_loader.md)

View File

@@ -0,0 +1,6 @@
# Models
::: docforge.models
- [Module](module.md)
- [Object](object.md)
- [Project](project.md)

View File

@@ -0,0 +1,7 @@
# Nav
::: docforge.nav
- [Mkdocs](mkdocs.md)
- [Resolver](resolver.md)
- [Spec](spec.md)
- [Wiki](wiki.md)

View File

@@ -0,0 +1,3 @@
# Wiki
::: docforge.nav.wiki

View File

@@ -0,0 +1,6 @@
# Renderers
::: docforge.renderers
- [Base](base.md)
- [Mcp Renderer](mcp_renderer.md)
- [Mkdocs Renderer](mkdocs_renderer.md)

View File

@@ -0,0 +1,4 @@
# Servers
::: docforge.servers
- [Mcp Server](mcp_server.md)

View File

@@ -1,3 +1,4 @@
# docforge # docforge
::: docforge ::: docforge
- [Docforge](docforge/)

View File

@@ -0,0 +1,3 @@
# Griffe Loader
::: docforge.loaders.griffe_loader

View File

@@ -0,0 +1,3 @@
# Module
::: docforge.models.module

View File

@@ -0,0 +1,3 @@
# Object
::: docforge.models.object

View File

@@ -0,0 +1,3 @@
# Project
::: docforge.models.project

3
docs/lib/nav/mkdocs.md Normal file
View File

@@ -0,0 +1,3 @@
# Mkdocs
::: docforge.nav.mkdocs

3
docs/lib/nav/resolver.md Normal file
View File

@@ -0,0 +1,3 @@
# Resolver
::: docforge.nav.resolver

3
docs/lib/nav/spec.md Normal file
View File

@@ -0,0 +1,3 @@
# Spec
::: docforge.nav.spec

View File

@@ -0,0 +1,3 @@
# Base
::: docforge.renderers.base

View File

@@ -0,0 +1,3 @@
# Mcp Renderer
::: docforge.renderers.mcp_renderer

Some files were not shown because too many files have changed in this diff Show More