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

fixes for bland looking doc strings

Browse Source
This commit is contained in:
Vishesh 'ironeagle' Bangotra
2026-02-27 20:47:23 +05:30
parent 066e710dee
commit 6c8da4b43b
2 changed files with 52 additions and 33 deletions
Download Patch File Download Diff File Expand all files Collapse all files

83
docforge/__init__.py
View File

@@ -5,7 +5,6 @@ structured documentation for both humans (MkDocs) and machines (MCP / AI agents)
`doc-forge` statically analyzes your source code, builds a semantic model of `doc-forge` statically analyzes your source code, builds a semantic model of
modules and objects, and renders that model into documentation outputs without modules and objects, and renders that model into documentation outputs without
executing your code. executing your code.
--- ---
## Core Philosophy ## Core Philosophy
@@ -30,7 +29,6 @@ Example:
```python ```python
from my_package.foo import Bar from my_package.foo import Bar
``` ```
--- ---
## Docstring Writing Standard ## Docstring Writing Standard
@@ -39,7 +37,6 @@ Docstrings are the single source of truth. `doc-forge` does not generate content
It compiles and renders what you write. It compiles and renders what you write.
Documentation follows the Python import hierarchy. Documentation follows the Python import hierarchy.
--- ---
## Package docstring (`package/__init__.py`) — Full user guide ## Package docstring (`package/__init__.py`) — Full user guide
@@ -49,44 +46,46 @@ package after reading only this docstring.
Example: Example:
```python
''' '''
my_package
Short description of what this package provides. Short description of what this package provides.
## Installation ## Installation
```bash
pip install my-package pip install my-package
```
## Quick start ## Quick start
```python
from my_package.foo import Bar from my_package.foo import Bar
bar = Bar() bar = Bar()
result = bar.process("example") result = bar.process("example")
```
---
## Core concepts ## Core concepts
Bar ### Bar
Primary object exposed by the package. - Primary object exposed by the package.
foo module ### foo module
Provides core functionality. - Provides core functionality.
---
## Typical workflow ## Typical workflow
1. Import public objects 1. Import public objects
2. Initialize objects 2. Initialize objects
3. Call methods 3. Call methods
---
## Public API ## Public API
foo.Bar foo.Bar
foo.helper_function foo.helper_function
''' '''
```
--- ---
## Submodule docstring (`package/foo/__init__.py`) — Subsystem guide ## Submodule docstring (`package/foo/__init__.py`) — Subsystem guide
@@ -95,21 +94,18 @@ Explains a specific subsystem.
Example: Example:
```python
''' '''
foo subsystem.
Provides core functionality. Provides core functionality.
## Usage ## Usage
```python
from my_package.foo import Bar from my_package.foo import Bar
bar = Bar() bar = Bar()
bar.process("example") bar.process("example")
'''
``` ```
'''
--- ---
## Class docstring — Object contract ## Class docstring — Object contract
@@ -133,7 +129,6 @@ Include:
* Lifecycle expectations * Lifecycle expectations
* Thread safety (if relevant) * Thread safety (if relevant)
* Performance characteristics (if relevant) * Performance characteristics (if relevant)
--- ---
## Function and method docstrings — API specification ## Function and method docstrings — API specification
@@ -145,19 +140,25 @@ def process(self, value: str) -> str:
''' '''
Process an input value. Process an input value.
Args: Parameters
value: ----------
Input string. value : str
value to be processed
Example:
'string'
Returns: Returns
Processed string. -------
processed value : str
result after processing value
---
Raises: Behavior
ValueError: --------
If the input is invalid. - behaviour 1
- behaviour 2
''' '''
``` ```
--- ---
## Attribute docstrings (optional) ## Attribute docstrings (optional)
@@ -165,10 +166,27 @@ def process(self, value: str) -> str:
Example: Example:
```python ```python
self.name: str class Class
'''Identifier used during processing.''' '''
``` attribute1 : str
required: True
default: "default value"
attribute description
attribute2 : str
required: False
attribute description
attribute2 : str
required: False
default: "default value"
attribute description
'''
attribute1: str = "default value"
attribute2: str | None = None
attribute3: str | None = "default value"
```
--- ---
## Writing Rules ## Writing Rules
@@ -176,6 +194,8 @@ self.name: str
**Required** **Required**
* Use Markdown headings * Use Markdown headings
* Use Markdown line separator `---`
* Line separator should be followed by a blank line
* Provide real import examples * Provide real import examples
* Document all public APIs * Document all public APIs
* Keep descriptions precise and factual * Keep descriptions precise and factual
@@ -185,12 +205,11 @@ self.name: str
* Plain-text separators like `====` * Plain-text separators like `====`
* Duplicate external documentation * Duplicate external documentation
* Informal or conversational language * Informal or conversational language
--- ---
## How doc-forge uses these docstrings ## How doc-forge uses these docstrings
Build MkDocs site: ### Build MkDocs site:
```bash ```bash
doc-forge build --mkdocs --module my_package doc-forge build --mkdocs --module my_package

2
mcp_docs/modules/docforge.json
View File

@@ -2,7 +2,7 @@
"module": "docforge", "module": "docforge",
"content": { "content": {
"path": "docforge", "path": "docforge",
"docstring": "Renderer-agnostic Python documentation compiler that converts docstrings into\nstructured documentation for both humans (MkDocs) and machines (MCP / AI agents).\n\n`doc-forge` statically analyzes your source code, builds a semantic model of\nmodules and objects, and renders that model into documentation outputs without\nexecuting your code.\n\n---\n\n## Core Philosophy\n\n`doc-forge` follows a compiler architecture:\n\n1. **Front-end (Introspection)**\n Static analysis of modules, classes, functions, signatures, and docstrings.\n\n2. **Middle-end (Semantic Model)**\n Renderer-neutral structured representation of your API.\n\n3. **Back-end (Renderers)**\n\n * MkDocs → human documentation\n * MCP JSON → AI-readable documentation\n\nThe atomic unit of documentation is the Python import path.\n\nExample:\n\n```python\nfrom my_package.foo import Bar\n```\n\n---\n\n## Docstring Writing Standard\n\nDocstrings are the single source of truth. `doc-forge` does not generate content.\nIt compiles and renders what you write.\n\nDocumentation follows the Python import hierarchy.\n\n---\n\n## Package docstring (`package/__init__.py`) — Full user guide\n\nThis is the landing page. A developer must be able to install and use the\npackage after reading only this docstring.\n\nExample:\n\n```python\n'''\nmy_package\n\nShort description of what this package provides.\n\n## Installation\n\npip install my-package\n\n## Quick start\n\nfrom my_package.foo import Bar\n\nbar = Bar()\nresult = bar.process(\"example\")\n\n## Core concepts\n\nBar\n Primary object exposed by the package.\n\nfoo module\n Provides core functionality.\n\n## Typical workflow\n\n1. Import public objects\n2. Initialize objects\n3. Call methods\n\n## Public API\n\nfoo.Bar\nfoo.helper_function\n'''\n```\n\n---\n\n## Submodule docstring (`package/foo/__init__.py`) — Subsystem guide\n\nExplains a specific subsystem.\n\nExample:\n\n```python\n'''\nfoo subsystem.\n\nProvides core functionality.\n\n## Usage\n\nfrom my_package.foo import Bar\n\nbar = Bar()\nbar.process(\"example\")\n'''\n```\n\n---\n\n## Class docstring — Object contract\n\nDefines responsibility and behavior.\n\nExample:\n\n```python\nclass Bar:\n '''\n Performs processing on input data.\n\n Instances may be reused across multiple calls.\n '''\n```\n\nInclude:\n\n* Responsibility\n* Lifecycle expectations\n* Thread safety (if relevant)\n* Performance characteristics (if relevant)\n\n---\n\n## Function and method docstrings — API specification\n\nExample:\n\n```python\ndef process(self, value: str) -> str:\n '''\n Process an input value.\n\n Args:\n value:\n Input string.\n\n Returns:\n Processed string.\n\n Raises:\n ValueError:\n If the input is invalid.\n '''\n```\n\n---\n\n## Attribute docstrings (optional)\n\nExample:\n\n```python\nself.name: str\n'''Identifier used during processing.'''\n```\n\n---\n\n## Writing Rules\n\n**Required**\n\n* Use Markdown headings\n* Provide real import examples\n* Document all public APIs\n* Keep descriptions precise and factual\n\n**Avoid**\n\n* Plain-text separators like `====`\n* Duplicate external documentation\n* Informal or conversational language\n\n---\n\n## How doc-forge uses these docstrings\n\nBuild MkDocs site:\n\n```bash\ndoc-forge build --mkdocs --module my_package\n```\n\nBuild MCP documentation:\n\n```bash\ndoc-forge build --mcp --module my_package\n```\n\nBoth outputs are generated directly from docstrings.", "docstring": "Renderer-agnostic Python documentation compiler that converts docstrings into\nstructured documentation for both humans (MkDocs) and machines (MCP / AI agents).\n\n`doc-forge` statically analyzes your source code, builds a semantic model of\nmodules and objects, and renders that model into documentation outputs without\nexecuting your code.\n---\n\n## Core Philosophy\n\n`doc-forge` follows a compiler architecture:\n\n1. **Front-end (Introspection)**\n Static analysis of modules, classes, functions, signatures, and docstrings.\n\n2. **Middle-end (Semantic Model)**\n Renderer-neutral structured representation of your API.\n\n3. **Back-end (Renderers)**\n\n * MkDocs → human documentation\n * MCP JSON → AI-readable documentation\n\nThe atomic unit of documentation is the Python import path.\n\nExample:\n\n```python\nfrom my_package.foo import Bar\n```\n---\n\n## Docstring Writing Standard\n\nDocstrings are the single source of truth. `doc-forge` does not generate content.\nIt compiles and renders what you write.\n\nDocumentation follows the Python import hierarchy.\n---\n\n## Package docstring (`package/__init__.py`) — Full user guide\n\nThis is the landing page. A developer must be able to install and use the\npackage after reading only this docstring.\n\nExample:\n\n'''\nShort description of what this package provides.\n\n## Installation\n\n```bash\npip install my-package\n```\n\n## Quick start\n\n```python\nfrom my_package.foo import Bar\n\nbar = Bar()\nresult = bar.process(\"example\")\n```\n---\n\n## Core concepts\n\n### Bar\n- Primary object exposed by the package.\n\n### foo module\n- Provides core functionality.\n---\n\n## Typical workflow\n\n1. Import public objects\n2. Initialize objects\n3. Call methods\n---\n\n## Public API\n\nfoo.Bar\nfoo.helper_function\n'''\n---\n\n## Submodule docstring (`package/foo/__init__.py`) — Subsystem guide\n\nExplains a specific subsystem.\n\nExample:\n\n'''\nProvides core functionality.\n\n## Usage\n\n```python\nfrom my_package.foo import Bar\n\nbar = Bar()\nbar.process(\"example\")\n```\n'''\n---\n\n## Class docstring — Object contract\n\nDefines responsibility and behavior.\n\nExample:\n\n```python\nclass Bar:\n '''\n Performs processing on input data.\n\n Instances may be reused across multiple calls.\n '''\n```\n\nInclude:\n\n* Responsibility\n* Lifecycle expectations\n* Thread safety (if relevant)\n* Performance characteristics (if relevant)\n---\n\n## Function and method docstrings — API specification\n\nExample:\n\n```python\ndef process(self, value: str) -> str:\n '''\n Process an input value.\n\n Parameters\n ----------\n value : str\n value to be processed\n Example:\n 'string'\n\n Returns\n -------\n processed value : str\n result after processing value\n ---\n\n Behavior\n --------\n - behaviour 1\n - behaviour 2\n '''\n```\n---\n\n## Attribute docstrings (optional)\n\nExample:\n\n```python\nclass Class\n '''\n attribute1 : str\n required: True\n default: \"default value\"\n attribute description\n\n attribute2 : str\n required: False\n attribute description\n\n attribute2 : str\n required: False\n default: \"default value\"\n attribute description\n '''\n\n attribute1: str = \"default value\"\n attribute2: str | None = None\n attribute3: str | None = \"default value\"\n```\n---\n\n## Writing Rules\n\n**Required**\n\n* Use Markdown headings\n* Use Markdown line separator `---`\n* Line separator should be followed by a blank line\n* Provide real import examples\n* Document all public APIs\n* Keep descriptions precise and factual\n\n**Avoid**\n\n* Plain-text separators like `====`\n* Duplicate external documentation\n* Informal or conversational language\n---\n\n## How doc-forge uses these docstrings\n\n### Build MkDocs site:\n\n```bash\ndoc-forge build --mkdocs --module my_package\n```\n\nBuild MCP documentation:\n\n```bash\ndoc-forge build --mcp --module my_package\n```\n\nBoth outputs are generated directly from docstrings.",
"objects": { "objects": {
"GriffeLoader": { "GriffeLoader": {
"name": "GriffeLoader", "name": "GriffeLoader",