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

doc string changes with sample to generate doc strings for packages/modules

Browse Source
This commit is contained in:
Vishesh 'ironeagle' Bangotra
2026-02-27 14:10:15 +05:30
parent fbe9e1f109
commit ed0fac8b3d
1 changed files with 181 additions and 59 deletions
Download Patch File Download Diff File Expand all files Collapse all files

240
docforge/__init__.py
View File

@@ -1,86 +1,208 @@
"""
# doc-forge
Renderer-agnostic Python documentation compiler that converts docstrings into
structured documentation for both humans (MkDocs) and machines (MCP / AI agents).
`doc-forge` is a renderer-agnostic Python documentation compiler designed for
speed, flexibility, and beautiful output. It decouples the introspection of
your code from the rendering process, allowing you to generate documentation
for various platforms (starting with MkDocs) from a single internal models.
`doc-forge` statically analyzes your source code, builds a semantic model of
modules and objects, and renders that model into documentation outputs without
executing your code.
---
## Core Philosophy
`doc-forge` operates on two fundamental principles:
`doc-forge` follows a compiler architecture:
1. **The Atomic Unit is a Python Import Path**: Documentation is organized around the semantic structure of your code (e.g., `mypackage.utils`), not the filesystem.
2. **The Documentation Compiler Paradigm**: We separate documentation into three distinct phases:
- **Front-end (Introspection)**: Static analysis of source code and docstrings.
- **Middle-end (Semantic Model)**: A renderer-neutral internal representation.
- **Back-end (Renderers)**: Generation of human-facing (MkDocs) or machine-facing (MCP) outputs.
1. **Front-end (Introspection)**
Static analysis of modules, classes, functions, signatures, and docstrings.
## Documentation Design
2. **Middle-end (Semantic Model)**
Renderer-neutral structured representation of your API.
`doc-forge` is an "AI-Native" documentation compiler. To get the most out of it, design your docstrings with both humans and LLMs in mind:
3. **Back-end (Renderers)**
### For Humans (Readability & Structure)
- **`__init__.py` as Landing Pages**: Use the docstring of your package's `__init__.py` as the home page. Include overviews, installation instructions, and high-level examples here.
- **Single Source of Truth**: Keep all technical details in docstrings. This ensures your MkDocs/Sphinx sites stay in sync with the code.
- **Semantic Hierarchy**: Use standard Markdown headers to structure complex module documentation.
* MkDocs → human documentation
* MCP JSON → AI-readable documentation
### For LLMs (AI-Native Knowledge)
- **Model Context Protocol (MCP)**: `doc-forge` exports your docs as structured JSON. This allows AI agents to "understand" your API surface area without layout noise.
- **Canonical Paths**: Use dotted import paths as primary identifiers. AI tools use these to link code usage to documentation.
- **Type Annotations**: While not in docstrings, `doc-forge` (via Griffe) extracts signatures. Clean type hints dramatically improve an LLM's ability to generate correct code using your library.
## Available Commands
The atomic unit of documentation is the Python import path.
- **build**: Build documentation (MkDocs site or MCP resources).
- **serve**: Serve documentation (MkDocs or MCP).
- **tree**: Visualize the introspected project structure.
Example:
```python
from my_package.foo import Bar
```
---
## Docstring Writing Standard
Docstrings are the single source of truth. `doc-forge` does not generate content.
It compiles and renders what you write.
Documentation follows the Python import hierarchy.
---
## Package docstring (`package/__init__.py`) — Full user guide
This is the landing page. A developer must be able to install and use the
package after reading only this docstring.
Example:
```python
'''
my_package
Short description of what this package provides.
## Installation
Install using `pip` with the optional `mkdocs` dependencies for a complete setup:
pip install my-package
```bash
pip install doc-forge
## Quick start
from my_package.foo import Bar
bar = Bar()
result = bar.process("example")
## Core concepts
Bar
Primary object exposed by the package.
foo module
Provides core functionality.
## Typical workflow
1. Import public objects
2. Initialize objects
3. Call methods
## Public API
foo.Bar
foo.helper_function
'''
```
## Quick Start
---
1. **Build Documentation**:
Introspect your package and generate documentation in one step:
```bash
# Build MkDocs site
doc-forge build --mkdocs --module my_package --site-name "My Docs"
## Submodule docstring (`package/foo/__init__.py`) — Subsystem guide
# Build MCP resources
doc-forge build --mcp --module my_package
```
Explains a specific subsystem.
2. **Define Navigation**:
Create a `docforge.nav.yml` to organize your documentation:
```yaml
home: my_package/index.md
groups:
Core API:
- my_package/core/*.md
Utilities:
- my_package/utils.md
```
Example:
3. **Preview**:
```bash
# Serve MkDocs site
doc-forge serve --mkdocs
```python
'''
foo subsystem.
# Serve MCP documentation
doc-forge serve --mcp
```
Provides core functionality.
## Project Structure
## Usage
- `docforge.loaders`: Introspects source code using static analysis (`griffe`).
- `docforge.models`: The internal representation of your project, modules, and objects.
- `docforge.renderers`: Converters that turn the models into physical files.
- `docforge.nav`: Managers for logical-to-physical path mapping and navigation.
from my_package.foo import Bar
bar = Bar()
bar.process("example")
'''
```
---
## Class docstring — Object contract
Defines responsibility and behavior.
Example:
```python
class Bar:
'''
Performs processing on input data.
Instances may be reused across multiple calls.
'''
```
Include:
* Responsibility
* Lifecycle expectations
* Thread safety (if relevant)
* Performance characteristics (if relevant)
---
## Function and method docstrings — API specification
Example:
```python
def process(self, value: str) -> str:
'''
Process an input value.
Args:
value:
Input string.
Returns:
Processed string.
Raises:
ValueError:
If the input is invalid.
'''
```
---
## Attribute docstrings (optional)
Example:
```python
self.name: str
'''Identifier used during processing.'''
```
---
## Writing Rules
**Required**
* Use Markdown headings
* Provide real import examples
* Document all public APIs
* Keep descriptions precise and factual
**Avoid**
* Plain-text separators like `====`
* Duplicate external documentation
* Informal or conversational language
---
## How doc-forge uses these docstrings
Build MkDocs site:
```bash
doc-forge build --mkdocs --module my_package
```
Build MCP documentation:
```bash
doc-forge build --mcp --module my_package
```
Both outputs are generated directly from docstrings.
"""
from .loaders import GriffeLoader, discover_module_paths