diff --git a/docforge/__init__.py b/docforge/__init__.py index 5ece5b8..1bd88d1 100644 --- a/docforge/__init__.py +++ b/docforge/__init__.py @@ -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 diff --git a/mcp_docs/modules/docforge.json b/mcp_docs/modules/docforge.json index c06c6b0..15fcb39 100644 --- a/mcp_docs/modules/docforge.json +++ b/mcp_docs/modules/docforge.json @@ -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",