From 04db9f44d86aa14495b53db07e8b9e4f7c30fe1b Mon Sep 17 00:00:00 2001 From: Vishesh 'ironeagle' Bangotra Date: Fri, 27 Feb 2026 21:05:15 +0530 Subject: [PATCH] fixes for broken Examples and other formatting issues --- docforge/__init__.py | 114 +++++++++++++++++++-------------- mcp_docs/modules/docforge.json | 2 +- 2 files changed, 67 insertions(+), 49 deletions(-) diff --git a/docforge/__init__.py b/docforge/__init__.py index 0a702ce..5ece5b8 100644 --- a/docforge/__init__.py +++ b/docforge/__init__.py @@ -21,14 +21,6 @@ executing your code. * MkDocs → human documentation * MCP JSON → AI-readable documentation - -The atomic unit of documentation is the Python import path. - -Example: - -```python -from my_package.foo import Bar -``` --- ## Docstring Writing Standard @@ -46,46 +38,47 @@ package after reading only this docstring. Example: -''' -Short description of what this package provides. + ''' + Short description of what this package provides. -## Installation + ## Installation -```bash -pip install my-package -``` + ```bash + pip install my-package + ``` -## Quick start + ## Quick start -```python -from my_package.foo import Bar + ```python + from my_package.foo import Bar -bar = Bar() -result = bar.process("example") -``` ---- + bar = Bar() + result = bar.process("example") + ``` + --- -## Core concepts + ## 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 + ## Typical workflow -1. Import public objects -2. Initialize objects -3. Call methods ---- + 1. Import public objects + 2. Initialize objects + 3. Call methods + --- -## Public API + ## Public API -foo.Bar -foo.helper_function -''' + foo.Bar + foo.helper_function + --- + ''' --- ## Submodule docstring (`package/foo/__init__.py`) — Subsystem guide @@ -94,18 +87,19 @@ Explains a specific subsystem. Example: -''' -Provides core functionality. + ''' + Provides core functionality. -## Usage + ## Usage -```python -from my_package.foo import Bar + ```python + from my_package.foo import Bar -bar = Bar() -bar.process("example") -``` -''' + bar = Bar() + bar.process("example") + ``` + --- + ''' --- ## Class docstring — Object contract @@ -120,6 +114,7 @@ class Bar: Performs processing on input data. Instances may be reused across multiple calls. + --- ''' ``` @@ -136,17 +131,38 @@ Include: Example: ```python -def process(self, value: str) -> str: +def process( + self, + value1: str, + value2: str | None = "default value", + value3: str | None = None, +) -> str: ''' Process an input value. + --- Parameters ---------- - value : str + value1 : str + required: True value to be processed Example: 'string' + value2 : str + required: False + default: "default value" + value to be processed + Example: + 'string' + + value3 : str + required: False + value to be processed + Example: + 'string' + --- + Returns ------- processed value : str @@ -157,6 +173,7 @@ def process(self, value: str) -> str: -------- - behaviour 1 - behaviour 2 + --- ''' ``` --- @@ -215,13 +232,14 @@ class Class doc-forge build --mkdocs --module my_package ``` -Build MCP documentation: +### Build MCP documentation: ```bash doc-forge build --mcp --module my_package ``` Both outputs are generated directly from docstrings. +--- """ from .loaders import GriffeLoader, discover_module_paths diff --git a/mcp_docs/modules/docforge.json b/mcp_docs/modules/docforge.json index 8312cf1..c06c6b0 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\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.", + "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---", "objects": { "GriffeLoader": { "name": "GriffeLoader",