minor formatting changes
This commit is contained in:
@@ -7,7 +7,7 @@ modules and objects, and renders that model into documentation outputs without
|
||||
executing your code.
|
||||
---
|
||||
|
||||
## Core Philosophy
|
||||
# Core Philosophy
|
||||
|
||||
`doc-forge` follows a compiler architecture:
|
||||
|
||||
@@ -23,7 +23,7 @@ executing your code.
|
||||
* MCP JSON → AI-readable documentation
|
||||
---
|
||||
|
||||
## Docstring Writing Standard
|
||||
# Docstring Writing Standard
|
||||
|
||||
Docstrings are the single source of truth. `doc-forge` does not generate content.
|
||||
It compiles and renders what you write.
|
||||
@@ -31,23 +31,23 @@ It compiles and renders what you write.
|
||||
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
|
||||
package after reading only this docstring.
|
||||
|
||||
Example:
|
||||
## Example:
|
||||
|
||||
'''
|
||||
Short description of what this package provides.
|
||||
|
||||
## Installation
|
||||
# Installation
|
||||
|
||||
```bash
|
||||
pip install my-package
|
||||
```
|
||||
|
||||
## Quick start
|
||||
# Quick start
|
||||
|
||||
```python
|
||||
from my_package.foo import Bar
|
||||
@@ -57,23 +57,23 @@ Example:
|
||||
```
|
||||
---
|
||||
|
||||
## Core concepts
|
||||
# Core concepts
|
||||
|
||||
### Bar
|
||||
## Bar
|
||||
- Primary object exposed by the package.
|
||||
|
||||
### foo module
|
||||
## foo module
|
||||
- Provides core functionality.
|
||||
---
|
||||
|
||||
## Typical workflow
|
||||
# Typical workflow
|
||||
|
||||
1. Import public objects
|
||||
2. Initialize objects
|
||||
3. Call methods
|
||||
---
|
||||
|
||||
## Public API
|
||||
# Public API
|
||||
|
||||
foo.Bar
|
||||
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.
|
||||
|
||||
Example:
|
||||
## Example:
|
||||
|
||||
'''
|
||||
Provides core functionality.
|
||||
|
||||
## Usage
|
||||
# Usage
|
||||
|
||||
```python
|
||||
from my_package.foo import Bar
|
||||
@@ -102,11 +102,11 @@ Example:
|
||||
'''
|
||||
---
|
||||
|
||||
## Class docstring — Object contract
|
||||
# Class docstring — Object contract
|
||||
|
||||
Defines responsibility and behavior.
|
||||
|
||||
Example:
|
||||
## Example:
|
||||
|
||||
```python
|
||||
class Bar:
|
||||
@@ -126,9 +126,9 @@ Include:
|
||||
* Performance characteristics (if relevant)
|
||||
---
|
||||
|
||||
## Function and method docstrings — API specification
|
||||
# Function and method docstrings — API specification
|
||||
|
||||
Example:
|
||||
## Example:
|
||||
|
||||
```python
|
||||
def process(
|
||||
@@ -178,9 +178,9 @@ def process(
|
||||
```
|
||||
---
|
||||
|
||||
## Attribute docstrings (optional)
|
||||
# Attribute docstrings (optional)
|
||||
|
||||
Example:
|
||||
## Example:
|
||||
|
||||
```python
|
||||
class Class
|
||||
@@ -206,7 +206,7 @@ class Class
|
||||
```
|
||||
---
|
||||
|
||||
## Writing Rules
|
||||
# Writing Rules
|
||||
|
||||
**Required**
|
||||
|
||||
@@ -224,15 +224,15 @@ class Class
|
||||
* Informal or conversational language
|
||||
---
|
||||
|
||||
## How doc-forge uses these docstrings
|
||||
# How doc-forge uses these docstrings
|
||||
|
||||
### Build MkDocs site:
|
||||
## Build MkDocs site:
|
||||
|
||||
```bash
|
||||
doc-forge build --mkdocs --module my_package
|
||||
```
|
||||
|
||||
### Build MCP documentation:
|
||||
## Build MCP documentation:
|
||||
|
||||
```bash
|
||||
doc-forge build --mcp --module my_package
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
"module": "docforge",
|
||||
"content": {
|
||||
"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": {
|
||||
"GriffeLoader": {
|
||||
"name": "GriffeLoader",
|
||||
|
||||
Reference in New Issue
Block a user