fixes for bland looking doc strings
This commit is contained in:
@@ -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
|
||||
modules and objects, and renders that model into documentation outputs without
|
||||
executing your code.
|
||||
|
||||
---
|
||||
|
||||
## Core Philosophy
|
||||
@@ -30,7 +29,6 @@ Example:
|
||||
```python
|
||||
from my_package.foo import Bar
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 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.
|
||||
|
||||
Documentation follows the Python import hierarchy.
|
||||
|
||||
---
|
||||
|
||||
## Package docstring (`package/__init__.py`) — Full user guide
|
||||
@@ -49,44 +46,46 @@ package after reading only this docstring.
|
||||
|
||||
Example:
|
||||
|
||||
```python
|
||||
'''
|
||||
my_package
|
||||
|
||||
Short description of what this package provides.
|
||||
|
||||
## Installation
|
||||
|
||||
```bash
|
||||
pip install my-package
|
||||
```
|
||||
|
||||
## Quick start
|
||||
|
||||
```python
|
||||
from my_package.foo import Bar
|
||||
|
||||
bar = Bar()
|
||||
result = bar.process("example")
|
||||
```
|
||||
---
|
||||
|
||||
## Core concepts
|
||||
|
||||
Bar
|
||||
Primary object exposed by the package.
|
||||
### Bar
|
||||
- Primary object exposed by the package.
|
||||
|
||||
foo module
|
||||
Provides core functionality.
|
||||
### foo module
|
||||
- Provides core functionality.
|
||||
---
|
||||
|
||||
## Typical workflow
|
||||
|
||||
1. Import public objects
|
||||
2. Initialize objects
|
||||
3. Call methods
|
||||
---
|
||||
|
||||
## Public API
|
||||
|
||||
foo.Bar
|
||||
foo.helper_function
|
||||
'''
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Submodule docstring (`package/foo/__init__.py`) — Subsystem guide
|
||||
@@ -95,21 +94,18 @@ Explains a specific subsystem.
|
||||
|
||||
Example:
|
||||
|
||||
```python
|
||||
'''
|
||||
foo subsystem.
|
||||
|
||||
Provides core functionality.
|
||||
|
||||
## Usage
|
||||
|
||||
```python
|
||||
from my_package.foo import Bar
|
||||
|
||||
bar = Bar()
|
||||
bar.process("example")
|
||||
'''
|
||||
```
|
||||
|
||||
'''
|
||||
---
|
||||
|
||||
## Class docstring — Object contract
|
||||
@@ -133,7 +129,6 @@ Include:
|
||||
* Lifecycle expectations
|
||||
* Thread safety (if relevant)
|
||||
* Performance characteristics (if relevant)
|
||||
|
||||
---
|
||||
|
||||
## Function and method docstrings — API specification
|
||||
@@ -145,19 +140,25 @@ def process(self, value: str) -> str:
|
||||
'''
|
||||
Process an input value.
|
||||
|
||||
Args:
|
||||
value:
|
||||
Input string.
|
||||
Parameters
|
||||
----------
|
||||
value : str
|
||||
value to be processed
|
||||
Example:
|
||||
'string'
|
||||
|
||||
Returns:
|
||||
Processed string.
|
||||
Returns
|
||||
-------
|
||||
processed value : str
|
||||
result after processing value
|
||||
---
|
||||
|
||||
Raises:
|
||||
ValueError:
|
||||
If the input is invalid.
|
||||
Behavior
|
||||
--------
|
||||
- behaviour 1
|
||||
- behaviour 2
|
||||
'''
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Attribute docstrings (optional)
|
||||
@@ -165,10 +166,27 @@ def process(self, value: str) -> str:
|
||||
Example:
|
||||
|
||||
```python
|
||||
self.name: str
|
||||
'''Identifier used during processing.'''
|
||||
```
|
||||
class Class
|
||||
'''
|
||||
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
|
||||
@@ -176,6 +194,8 @@ self.name: str
|
||||
**Required**
|
||||
|
||||
* Use Markdown headings
|
||||
* Use Markdown line separator `---`
|
||||
* Line separator should be followed by a blank line
|
||||
* Provide real import examples
|
||||
* Document all public APIs
|
||||
* Keep descriptions precise and factual
|
||||
@@ -185,12 +205,11 @@ self.name: str
|
||||
* Plain-text separators like `====`
|
||||
* Duplicate external documentation
|
||||
* Informal or conversational language
|
||||
|
||||
---
|
||||
|
||||
## How doc-forge uses these docstrings
|
||||
|
||||
Build MkDocs site:
|
||||
### Build MkDocs site:
|
||||
|
||||
```bash
|
||||
doc-forge build --mkdocs --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\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": {
|
||||
"GriffeLoader": {
|
||||
"name": "GriffeLoader",
|
||||
|
||||
Reference in New Issue
Block a user