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

minor formatting changes

Browse Source
This commit is contained in:
Vishesh 'ironeagle' Bangotra
2026-02-27 21:16:05 +05:30
parent 7643e27358
commit caeda0ad5c
2 changed files with 25 additions and 25 deletions
Download Patch File Download Diff File Expand all files Collapse all files

48
docforge/__init__.py
View File

@@ -7,7 +7,7 @@ modules and objects, and renders that model into documentation outputs without
executing your code. executing your code.
--- ---
## Core Philosophy # Core Philosophy
`doc-forge` follows a compiler architecture: `doc-forge` follows a compiler architecture:
@@ -23,7 +23,7 @@ executing your code.
* MCP JSON → AI-readable documentation * MCP JSON → AI-readable documentation
--- ---
## Docstring Writing Standard # Docstring Writing Standard
Docstrings are the single source of truth. `doc-forge` does not generate content. 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.
@@ -31,23 +31,23 @@ 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
This is the landing page. A developer must be able to install and use the This is the landing page. A developer must be able to install and use the
package after reading only this docstring. package after reading only this docstring.
Example: ## Example:
''' '''
Short description of what this package provides. Short description of what this package provides.
## Installation # Installation
```bash ```bash
pip install my-package pip install my-package
``` ```
## Quick start # Quick start
```python ```python
from my_package.foo import Bar from my_package.foo import Bar
@@ -57,23 +57,23 @@ 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
@@ -81,16 +81,16 @@ Example:
''' '''
--- ---
## Submodule docstring (`package/foo/__init__.py`) — Subsystem guide # Submodule docstring (`package/foo/__init__.py`) — Subsystem guide
Explains a specific subsystem. Explains a specific subsystem.
Example: ## Example:
''' '''
Provides core functionality. Provides core functionality.
## Usage # Usage
```python ```python
from my_package.foo import Bar from my_package.foo import Bar
@@ -102,11 +102,11 @@ Example:
''' '''
--- ---
## Class docstring — Object contract # Class docstring — Object contract
Defines responsibility and behavior. Defines responsibility and behavior.
Example: ## Example:
```python ```python
class Bar: class Bar:
@@ -126,9 +126,9 @@ Include:
* Performance characteristics (if relevant) * Performance characteristics (if relevant)
--- ---
## Function and method docstrings — API specification # Function and method docstrings — API specification
Example: ## Example:
```python ```python
def process( def process(
@@ -178,9 +178,9 @@ def process(
``` ```
--- ---
## Attribute docstrings (optional) # Attribute docstrings (optional)
Example: ## Example:
```python ```python
class Class class Class
@@ -206,7 +206,7 @@ class Class
``` ```
--- ---
## Writing Rules # Writing Rules
**Required** **Required**
@@ -224,15 +224,15 @@ class Class
* 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
``` ```
### Build MCP documentation: ## Build MCP documentation:
```bash ```bash
doc-forge build --mcp --module my_package doc-forge build --mcp --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## 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---\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 '''\n Short description of what this package provides.\n\n ## Installation\n\n ```bash\n pip install my-package\n ```\n\n ## Quick start\n\n ```python\n from my_package.foo import Bar\n\n bar = Bar()\n result = 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\n 1. Import public objects\n 2. Initialize objects\n 3. Call methods\n ---\n\n ## Public API\n\n foo.Bar\n foo.helper_function\n ---\n '''\n---\n\n## Submodule docstring (`package/foo/__init__.py`) — Subsystem guide\n\nExplains a specific subsystem.\n\nExample:\n\n '''\n Provides core functionality.\n\n ## Usage\n\n ```python\n from my_package.foo import Bar\n\n bar = Bar()\n bar.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```\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(\n self,\n value1: str,\n value2: str | None = \"default value\",\n value3: str | None = None,\n) -> str:\n '''\n Process an input value.\n ---\n\n Parameters\n ----------\n value1 : str\n required: True\n value to be processed\n Example:\n 'string'\n\n value2 : str\n required: False\n default: \"default value\"\n value to be processed\n Example:\n 'string'\n\n value3 : str\n required: False\n value to be processed\n Example:\n 'string'\n ---\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\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\n### Build MCP documentation:\n\n```bash\ndoc-forge build --mcp --module my_package\n```\n\nBoth outputs are generated directly from docstrings.\n---", "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---\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\n## Example:\n\n '''\n Short description of what this package provides.\n\n # Installation\n\n ```bash\n pip install my-package\n ```\n\n # Quick start\n\n ```python\n from my_package.foo import Bar\n\n bar = Bar()\n result = 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\n 1. Import public objects\n 2. Initialize objects\n 3. Call methods\n ---\n\n # Public API\n\n foo.Bar\n foo.helper_function\n ---\n '''\n---\n\n# Submodule docstring (`package/foo/__init__.py`) — Subsystem guide\n\nExplains a specific subsystem.\n\n## Example:\n\n '''\n Provides core functionality.\n\n # Usage\n\n ```python\n from my_package.foo import Bar\n\n bar = Bar()\n bar.process(\"example\")\n ```\n ---\n '''\n---\n\n# Class docstring — Object contract\n\nDefines responsibility and behavior.\n\n## Example:\n\n```python\nclass Bar:\n '''\n Performs processing on input data.\n\n Instances may be reused across multiple calls.\n ---\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\n## Example:\n\n```python\ndef process(\n self,\n value1: str,\n value2: str | None = \"default value\",\n value3: str | None = None,\n) -> str:\n '''\n Process an input value.\n ---\n\n Parameters\n ----------\n value1 : str\n required: True\n value to be processed\n Example:\n 'string'\n\n value2 : str\n required: False\n default: \"default value\"\n value to be processed\n Example:\n 'string'\n\n value3 : str\n required: False\n value to be processed\n Example:\n 'string'\n ---\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\n# Attribute docstrings (optional)\n\n## Example:\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\n## Build MCP documentation:\n\n```bash\ndoc-forge build --mcp --module my_package\n```\n\nBoth outputs are generated directly from docstrings.\n---",
"objects": { "objects": {
"GriffeLoader": { "GriffeLoader": {
"name": "GriffeLoader", "name": "GriffeLoader",