From ed0fac8b3d77a4f7340a6355e88639a1cbacc6e8 Mon Sep 17 00:00:00 2001 From: Vishesh 'ironeagle' Bangotra Date: Fri, 27 Feb 2026 14:10:15 +0530 Subject: [PATCH] doc string changes with sample to generate doc strings for packages/modules --- docforge/__init__.py | 240 ++++++++++++++++++++++++++++++++----------- 1 file changed, 181 insertions(+), 59 deletions(-) diff --git a/docforge/__init__.py b/docforge/__init__.py index c195fbd..c94b934 100644 --- a/docforge/__init__.py +++ b/docforge/__init__.py @@ -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