From 27f76c78312feb675e5361dd48df7adfd07ee021 Mon Sep 17 00:00:00 2001 From: Vishesh 'ironeagle' Bangotra Date: Tue, 15 Sep 2026 14:02:07 +0530 Subject: [PATCH] docs(wiki): added more rules and explanation on how to use the prompt in docforge wiki --- doc-forge/wiki/03_conventions/index.html | 11 +- doc-forge/wiki/index.html | 503 +++++++++--------- doc-forge/wiki/search/search_index.json | 2 +- doc-forge/wiki/sitemap.xml.gz | Bin 127 -> 127 bytes .../modules/docforge.cli.commands.json | 8 +- mcp/doc-forge/modules/docforge.cli.json | 8 +- mcp/doc-forge/modules/docforge.json | 10 +- 7 files changed, 281 insertions(+), 261 deletions(-) diff --git a/doc-forge/wiki/03_conventions/index.html b/doc-forge/wiki/03_conventions/index.html index 261a0ad..a1516cc 100644 --- a/doc-forge/wiki/03_conventions/index.html +++ b/doc-forge/wiki/03_conventions/index.html @@ -466,9 +466,9 @@
  • - + - .pyi stubs + .pyi stubs and py.typed @@ -743,11 +743,14 @@ package docstring, which is exported verbatim into
  • Use Args:, Returns:, Raises:, Yields:, Notes:, and Example: sections at function and method level.
  • Always update the matching .pyi stub alongside the .py implementation.
    • +
  • Every distributable package ships a py.typed marker so type checkers + consume the authored signatures instead of Any.
    • -

    .pyi stubs

    +

    .pyi stubs and py.typed

    Every module ships a matching .pyi stub kept in sync with the .py -implementation. When signatures change, update both files.

    +implementation. When signatures change, update both files. Packages expose a +py.typed marker so consumers and type checkers use the authored signatures.

    Wiki pages

      diff --git a/doc-forge/wiki/index.html b/doc-forge/wiki/index.html index 5429634..afda55e 100644 --- a/doc-forge/wiki/index.html +++ b/doc-forge/wiki/index.html @@ -790,7 +790,8 @@ and testing recipes. The authoritative API contracts live in the code
      diff --git a/doc-forge/wiki/search/search_index.json b/doc-forge/wiki/search/search_index.json index 88b0ca9..89a44aa 100644 --- a/doc-forge/wiki/search/search_index.json +++ b/doc-forge/wiki/search/search_index.json @@ -1 +1 @@ -{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"\ud83e\udde9 docforge \u2014 Docstring-Driven Documentation Forge","text":"

      docforge is an internal documentation tool that generates reference documentation from Google-Styled Doc-Forge Convention (GSDFC) docstrings and assembles it into per-kind MkDocs sites, alongside hand-written wiki pages and OpenAPI-based API docs.

      Doc model: this wiki is written for humans \u2014 how\u2011to guides, examples, and testing recipes. The authoritative API contracts live in the code (docstrings) and the machine\u2011readable bundle under docs/mcp/.

      "},{"location":"#key-features","title":"\ud83d\ude80 Key Features","text":""},{"location":"#installation","title":"\ud83d\udce6 Installation","text":"
      # Internal PyPI (TBD)\npip install docforge\n
      "},{"location":"#documentation-structure","title":"\ud83d\udcc1 Documentation Structure","text":"Section Description Overview What docforge is and how it fits the pipeline Components Loaders, models, nav, renderers, CLI, servers Conventions GSDFC, .pyi stubs, and template conventions Iterative Workflow How a docs build runs end to end Environment Environment setup Quality Gates Test layout and quality checks GSDFC Guide How to write GSDFC-conformant docstrings MCP Guide Building, serving, and consuming the MCP bundle MkDocs Configs MkDocs config generation and templates"},{"location":"#related-resources","title":"\ud83d\udd17 Related Resources","text":"

      \u00a9 Aetoskia Internal \u2014 docforge 1.0

      "},{"location":"01_overview/","title":"Library Overview","text":"

      docforge turns GSDFC-compliant Python docstrings into maintainable reference documentation. It never edits source docstrings; it reads them, renders them, and assembles documentation sites from all available material.

      "},{"location":"01_overview/#which-build-should-you-use","title":"\ud83e\udded Which Build Should You Use?","text":"Kind Source Output lib GSDFC docstrings docs/lib/** rendered markdown api OpenAPI JSON spec docs/api/** rendered markdown wiki Hand-written markdown docs/wiki/** (unchanged) mcp GSDFC docstrings + renderers docs/mcp/** structured JSON"},{"location":"01_overview/#architecture","title":"\ud83c\udfd7\ufe0f Architecture","text":"

      Each enabled site kind produces its own MkDocs configuration and build:

      1. --mkdocs (lib) writes docs/mkdocs.lib.yml and builds site/lib/.
      2. --api writes docs/mkdocs.api.yml and builds site/api/.
      3. --wiki writes docs/mkdocs.wiki.yml and builds site/wiki/.

      Every site is self-contained (own theme assets and search index) with navigation derived or scoped to that kind. Hand-written wiki content is never overwritten or regenerated \u2014 only its navigation is derived automatically.

      "},{"location":"01_overview/#lifecycle-rules","title":"\ud83d\udd04 Lifecycle Rules","text":"

      docs/mcp/** is a self-contained, machine-readable reference generated from docforge's own GSDFC docstrings. doc-forge serve --mcp --module docforge serves it over MCP. See the MCP Guide.

      "},{"location":"01_overview/#read-next","title":"\u27a1\ufe0f Read Next","text":""},{"location":"02_components/","title":"Components","text":"

      docforge is split into four horizontal layers. Everything flows top to bottom through the CLI.

      "},{"location":"02_components/#1-loaders-models","title":"1. Loaders & Models","text":"

      The docforge/loaders package wraps griffe to extract modules, functions, classes, and Google-style docstring sections. Loaded data is normalized into the object model under docforge/models (Project, Module, DocObject).

      "},{"location":"02_components/#2-navigation","title":"2. Navigation","text":"

      docforge/nav parses docforge.nav.yml specs (NavSpec, Resolver, and the MkDocs nav emitter) and, since the wiki kind, derives wiki navigation from the file structure via build_wiki_nav.

      "},{"location":"02_components/#3-renderers","title":"3. Renderers","text":"

      docforge/renderers turn model data into artifacts:

      "},{"location":"02_components/#4-servers","title":"4. Servers","text":"

      docforge/servers serves generated artifacts over live protocols:

      "},{"location":"02_components/#5-cli","title":"5. CLI","text":"

      docforge/cli wires it all together:

      "},{"location":"02_components/#related","title":"Related","text":""},{"location":"03_conventions/","title":"Conventions","text":""},{"location":"03_conventions/#gsdfc-docstrings","title":"GSDFC docstrings","text":"

      All documented source uses the Google-Styled Doc-Forge Convention (GSDFC): Args:, Returns:, Raises:, and Attributes: sections with properly typed signatures.

      The authoritative GSDFC specification lives in the docforge/__init__.py package docstring, which is exported verbatim into docs/mcp/modules/docforge.json, so the MCP bundle is self-documenting.

      Key rules:

      1. Use parenthesized types in prose entries (name (Type):) that match the signature types.
      2. Use # Summary, # Examples, and # Notes sections at module level.
      3. Use Args:, Returns:, Raises:, Yields:, Notes:, and Example: sections at function and method level.
      4. Always update the matching .pyi stub alongside the .py implementation.
      "},{"location":"03_conventions/#pyi-stubs","title":".pyi stubs","text":"

      Every module ships a matching .pyi stub kept in sync with the .py implementation. When signatures change, update both files.

      "},{"location":"03_conventions/#wiki-pages","title":"Wiki pages","text":"
      1. Hand-written markdown lives in docs/wiki/** and is never generated.
      2. File names use a numeric prefix: 01_overview.md, 02_components.md.
      3. Nested directories become nested navigation groups: 05_development/01_environment.md \u2192 group Development.
      4. index.md is the site Home at the root, and a section root inside a directory.
      5. Navigation labels are derived by stripping the numeric prefix and applying title case on the remaining words.
      "},{"location":"03_conventions/#templates","title":"Templates","text":"

      MkDocs config fragments live in docforge/templates. The mkdocs.wiki.yml fragment carries only the search plugin, since wiki pages contain no mkdocstrings directives.

      "},{"location":"03_conventions/#related","title":"Related","text":""},{"location":"04_iterative_workflow/","title":"Iterative Workflow","text":"

      A docs build runs through the CLI in a single pass.

      "},{"location":"04_iterative_workflow/#build-commands","title":"\ud83d\ude80 Build commands","text":"
      # Library reference only\ndoc-forge build --mkdocs --module docforge\n\n# Wiki + library (each an independent MkDocs build)\ndoc-forge build --wiki --mkdocs --module docforge\n\n# Wiki only \u2014 no module required\ndoc-forge build --wiki --site-name docforge\n\n# MCP structured bundle\ndoc-forge build --mcp --module docforge\n
      "},{"location":"04_iterative_workflow/#what-a-build-does","title":"\ud83d\udd04 What a build does","text":"
      1. Validates the requested modes (--mkdocs, --api, --wiki, --mcp).
      2. Generates library sources under docs/lib/** with MkDocsRenderer.
      3. Generates API sources under docs/api/** when --api is given.
      4. Derives the wiki navigation from docs/wiki/**.
      5. Writes one MkDocs config per site kind (docs/mkdocs.{lib,api,wiki}.yml), re-rooting navigation paths to each kind's docs_dir.
      6. Runs mkdocs build once per config, emitting self-contained sites site/lib/, site/api/, and site/wiki/.
      "},{"location":"04_iterative_workflow/#explore-the-sites","title":"\ud83e\udded Explore the sites","text":"
      doc-forge build --wiki --mkdocs --module docforge\ndoc-forge serve --wiki       # serves site preview from docs/mkdocs.wiki.yml\ndoc-forge serve --lib\ndoc-forge serve --api\n# or target any config directly:\ndoc-forge serve --mkdocs --mkdocs-yml docs/mkdocs.wiki.yml\n
      "},{"location":"04_iterative_workflow/#serve-the-mcp-bundle","title":"\ud83d\udce6 Serve the MCP bundle","text":"
      doc-forge build --mcp --module docforge\ndoc-forge serve --mcp --module docforge\n
      "},{"location":"04_iterative_workflow/#related","title":"Related","text":""},{"location":"05_development/01_environment/","title":"Environment Setup","text":""},{"location":"05_development/01_environment/#create-the-environment","title":"\ud83d\ude80 Create the environment","text":"
      python -m venv .venv\n.venv\\Scripts\\activate\npip install -e .\n

      Requires Python 3.10+ (per pyproject.toml).

      "},{"location":"05_development/01_environment/#dependencies","title":"\ud83d\udce6 Dependencies","text":"

      Development extras include:

      "},{"location":"05_development/01_environment/#related","title":"Related","text":""},{"location":"05_development/02_quality_gates/","title":"Quality Gates","text":"

      Run all checks before pushing:

      "},{"location":"05_development/02_quality_gates/#commands","title":"\ud83d\ude80 Commands","text":"
      .venv\\Scripts\\python.exe -m pytest\n.venv\\Scripts\\python.exe -m ruff check docforge tests\n.venv\\Scripts\\python.exe -m black --check docforge tests\n.venv\\Scripts\\python.exe -m mypy docforge\n.venv\\Scripts\\pydoclint.exe docforge\n
      "},{"location":"05_development/02_quality_gates/#test-layout","title":"\ud83d\udcc1 Test layout","text":"Path Covers tests/nav/ Nav spec, resolver, wiki nav tests/cli/ Build command flows and modes tests/renderers/ MkDocs / MCP rendering

      CLI tests use the cli_runner fixture with mock_mkdocs_build and mock_mkdocs_load_config so they exercise the full flow without invoking a real MkDocs build.

      "},{"location":"05_development/02_quality_gates/#related","title":"Related","text":""},{"location":"05_development/03_gsdfc_guide/","title":"GSDFC Docstring Guide","text":"

      This page is the practical companion to the authoritative GSDFC specification in the docforge/__init__.py package docstring. It describes how to write docstrings that render correctly in MkDocs and stay machine-parseable by doc-forge, MkDocs, and MCP clients.

      "},{"location":"05_development/03_gsdfc_guide/#overview","title":"\ud83e\udded Overview","text":""},{"location":"05_development/03_gsdfc_guide/#module-docstrings","title":"\ud83d\udce6 Module docstrings","text":"

      Modules use Markdown headings and --- separators.

      Recommended sections:

      "},{"location":"05_development/03_gsdfc_guide/#class-docstrings","title":"\ud83d\udce6 Class docstrings","text":"

      Recommended sections, in order:

      "},{"location":"05_development/03_gsdfc_guide/#function-and-method-docstrings","title":"\ud83d\udce6 Function and method docstrings","text":"

      Recommended section order:

      1. Args:
      2. Returns:
      3. Raises:
      4. Yields:
      5. Notes:
      6. Example:

      Formatting rules:

      "},{"location":"05_development/03_gsdfc_guide/#property-docstrings","title":"\ud83d\udce6 Property docstrings","text":"

      Properties document their return values with a Returns: section and, when meaningful, an Example:.

      "},{"location":"05_development/03_gsdfc_guide/#example","title":"\ud83d\ude80 Example","text":"
      def process(foo: Foo, multiplier: int) -> int:\n    \"\"\"Process a Foo instance.\n\n    Args:\n        foo (Foo):\n            Foo instance to process.\n\n        multiplier (int):\n            Value used to scale foo.\n\n    Returns:\n        int:\n            Processed result.\n\n    Raises:\n        ValueError:\n            If multiplier is negative.\n\n    Example:\n        Process foo:\n\n            ```python\n            foo = Foo(\"example\", value=10)\n            result = process(foo, multiplier=2)\n            print(result)\n            ```\n    \"\"\"\n
      "},{"location":"05_development/03_gsdfc_guide/#keeping-stubs-in-sync","title":"\ud83d\udd04 Keeping stubs in sync","text":"

      Every .py module ships a matching .pyi stub. When a signature or a public symbol changes, update both files. Signature annotations in the stub must match the implementation.

      "},{"location":"05_development/03_gsdfc_guide/#enforcement","title":"\ud83d\udee1\ufe0f Enforcement","text":"

      pydoclint (Google style) runs in CI and verifies that Args:/Returns: sections match function signatures, including types.

      "},{"location":"05_development/03_gsdfc_guide/#related","title":"Related","text":""},{"location":"05_development/04_mcp_guide/","title":"MCP Guide","text":"

      Doc-forge can export a machine-readable MCP bundle from a project's GSDFC docstrings and serve that bundle over the Model Context Protocol (MCP). The bundle is self-contained: readers can derive the full API reference \u2014 signatures, docstrings, and structure \u2014 for the documented project.

      "},{"location":"05_development/04_mcp_guide/#building-the-bundle","title":"\ud83d\ude80 Building the bundle","text":"
      doc-forge build --mcp --module docforge\n

      This writes structured JSON into docs/mcp/:

      "},{"location":"05_development/04_mcp_guide/#serving-the-bundle","title":"\ud83d\ude80 Serving the bundle","text":"
      doc-forge serve --mcp --module docforge\n

      The MCPServer (in docforge/servers/mcp_server.py) exposes:

      Resource Description docs://index Project metadata docs://nav Navigation structure docs://modules/{module} Individual module documentation

      The server also registers a single diagnostic tool, ping, and is read-only. Missing resources are returned as structured error dictionaries rather than exceptions. The default transport is streamable-http; stdio and sse are supported via MCPServer.run.

      "},{"location":"05_development/04_mcp_guide/#bundle-contents","title":"\ud83d\udce6 Bundle contents","text":"

      Each module resource contains:

      Because the bundle is generated from docstrings, the quality of the bundle equals the quality of the project's GSDFC docstrings. For docforge itself, the GSDFC specification is carried in modules/docforge.json via the docforge/__init__.py package docstring, making the bundle self-documenting.

      "},{"location":"05_development/04_mcp_guide/#related","title":"Related","text":""},{"location":"05_development/05_mkdocs_configs/","title":"MkDocs Configuration Model","text":"

      Each documentation kind (lib, api, wiki) is built by its own MkDocs site. A repo that documents kind {kind} carries a config at docs/mkdocs.{kind}.yml that sets docs_dir to the kind's source directory and site_dir to ../site/{kind}.

      "},{"location":"05_development/05_mkdocs_configs/#file-wins","title":"\ud83d\udcc4 File wins","text":"

      docs/mkdocs.{kind}.yml is a repo-owned file, not a build byproduct:

      Because a present file is never rewritten, rerunning a build is a no-op for versioned configs: the working tree stays clean.

      "},{"location":"05_development/05_mkdocs_configs/#templates","title":"\ud83e\udde9 Templates","text":"

      The built-in defaults live in docforge/templates/:

      File Role mkdocs.common.yml Shared theme + markdown extensions mkdocs.lib.yml mkdocstrings handler for library reference mkdocs.api.yml Swagger/OpenAPI plugins and API-side features mkdocs.wiki.yml Wiki look: horizontal navigation.tabs header, blue grey/teal palette, Roboto

      A per-kind config is generated by deep-merging the common template with the kind fragment, then filling in generation-time values (site_name, docs_dir, site_dir, nav, API site_description/site_author, and the theme icon from docforge.nav.yml). Pass --template <path> to replace the built-in templates entirely.

      "},{"location":"05_development/05_mkdocs_configs/#supported-layouts","title":"\ud83c\udfd7\ufe0f Supported layouts","text":"

      Commit docs/mkdocs.{kind}.yml so served docs are reproducible from source.

      "},{"location":"05_development/05_mkdocs_configs/#related","title":"Related","text":""}]} \ No newline at end of file +{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"\ud83e\udde9 docforge \u2014 Docstring-Driven Documentation Forge","text":"

      docforge is an internal documentation tool that generates reference documentation from Google-Styled Doc-Forge Convention (GSDFC) docstrings and assembles it into per-kind MkDocs sites, alongside hand-written wiki pages and OpenAPI-based API docs.

      Doc model: this wiki is written for humans \u2014 how\u2011to guides, examples, and testing recipes. The authoritative API contracts live in the code (docstrings) and the machine\u2011readable bundle under docs/mcp/.

      "},{"location":"#key-features","title":"\ud83d\ude80 Key Features","text":""},{"location":"#installation","title":"\ud83d\udce6 Installation","text":"
      # Internal PyPI (TBD)\npip install docforge\n
      "},{"location":"#documentation-structure","title":"\ud83d\udcc1 Documentation Structure","text":"Section Description Overview What docforge is and how it fits the pipeline Components Loaders, models, nav, renderers, CLI, servers Conventions GSDFC, .pyi stubs, and template conventions Iterative Workflow How a docs build runs end to end Environment Environment setup Quality Gates Test layout and quality checks GSDFC Guide How to write GSDFC-conformant docstrings MCP Guide Building, serving, and consuming the MCP bundle MkDocs Configs MkDocs config generation and templates"},{"location":"#related-resources","title":"\ud83d\udd17 Related Resources","text":"

      \u00a9 Aetoskia Internal \u2014 docforge 1.0

      "},{"location":"01_overview/","title":"Library Overview","text":"

      docforge turns GSDFC-compliant Python docstrings into maintainable reference documentation. It never edits source docstrings; it reads them, renders them, and assembles documentation sites from all available material.

      "},{"location":"01_overview/#which-build-should-you-use","title":"\ud83e\udded Which Build Should You Use?","text":"Kind Source Output lib GSDFC docstrings docs/lib/** rendered markdown api OpenAPI JSON spec docs/api/** rendered markdown wiki Hand-written markdown docs/wiki/** (unchanged) mcp GSDFC docstrings + renderers docs/mcp/** structured JSON"},{"location":"01_overview/#architecture","title":"\ud83c\udfd7\ufe0f Architecture","text":"

      Each enabled site kind produces its own MkDocs configuration and build:

      1. --mkdocs (lib) writes docs/mkdocs.lib.yml and builds site/lib/.
      2. --api writes docs/mkdocs.api.yml and builds site/api/.
      3. --wiki writes docs/mkdocs.wiki.yml and builds site/wiki/.

      Every site is self-contained (own theme assets and search index) with navigation derived or scoped to that kind. Hand-written wiki content is never overwritten or regenerated \u2014 only its navigation is derived automatically.

      "},{"location":"01_overview/#lifecycle-rules","title":"\ud83d\udd04 Lifecycle Rules","text":"

      docs/mcp/** is a self-contained, machine-readable reference generated from docforge's own GSDFC docstrings. doc-forge serve --mcp --module docforge serves it over MCP. See the MCP Guide.

      "},{"location":"01_overview/#read-next","title":"\u27a1\ufe0f Read Next","text":""},{"location":"02_components/","title":"Components","text":"

      docforge is split into four horizontal layers. Everything flows top to bottom through the CLI.

      "},{"location":"02_components/#1-loaders-models","title":"1. Loaders & Models","text":"

      The docforge/loaders package wraps griffe to extract modules, functions, classes, and Google-style docstring sections. Loaded data is normalized into the object model under docforge/models (Project, Module, DocObject).

      "},{"location":"02_components/#2-navigation","title":"2. Navigation","text":"

      docforge/nav parses docforge.nav.yml specs (NavSpec, Resolver, and the MkDocs nav emitter) and, since the wiki kind, derives wiki navigation from the file structure via build_wiki_nav.

      "},{"location":"02_components/#3-renderers","title":"3. Renderers","text":"

      docforge/renderers turn model data into artifacts:

      "},{"location":"02_components/#4-servers","title":"4. Servers","text":"

      docforge/servers serves generated artifacts over live protocols:

      "},{"location":"02_components/#5-cli","title":"5. CLI","text":"

      docforge/cli wires it all together:

      "},{"location":"02_components/#related","title":"Related","text":""},{"location":"03_conventions/","title":"Conventions","text":""},{"location":"03_conventions/#gsdfc-docstrings","title":"GSDFC docstrings","text":"

      All documented source uses the Google-Styled Doc-Forge Convention (GSDFC): Args:, Returns:, Raises:, and Attributes: sections with properly typed signatures.

      The authoritative GSDFC specification lives in the docforge/__init__.py package docstring, which is exported verbatim into docs/mcp/modules/docforge.json, so the MCP bundle is self-documenting.

      Key rules:

      1. Use parenthesized types in prose entries (name (Type):) that match the signature types.
      2. Use # Summary, # Examples, and # Notes sections at module level.
      3. Use Args:, Returns:, Raises:, Yields:, Notes:, and Example: sections at function and method level.
      4. Always update the matching .pyi stub alongside the .py implementation.
      5. Every distributable package ships a py.typed marker so type checkers consume the authored signatures instead of Any.
      "},{"location":"03_conventions/#pyi-stubs-and-pytyped","title":".pyi stubs and py.typed","text":"

      Every module ships a matching .pyi stub kept in sync with the .py implementation. When signatures change, update both files. Packages expose a py.typed marker so consumers and type checkers use the authored signatures.

      "},{"location":"03_conventions/#wiki-pages","title":"Wiki pages","text":"
      1. Hand-written markdown lives in docs/wiki/** and is never generated.
      2. File names use a numeric prefix: 01_overview.md, 02_components.md.
      3. Nested directories become nested navigation groups: 05_development/01_environment.md \u2192 group Development.
      4. index.md is the site Home at the root, and a section root inside a directory.
      5. Navigation labels are derived by stripping the numeric prefix and applying title case on the remaining words.
      "},{"location":"03_conventions/#templates","title":"Templates","text":"

      MkDocs config fragments live in docforge/templates. The mkdocs.wiki.yml fragment carries only the search plugin, since wiki pages contain no mkdocstrings directives.

      "},{"location":"03_conventions/#related","title":"Related","text":""},{"location":"04_iterative_workflow/","title":"Iterative Workflow","text":"

      A docs build runs through the CLI in a single pass.

      "},{"location":"04_iterative_workflow/#build-commands","title":"\ud83d\ude80 Build commands","text":"
      # Library reference only\ndoc-forge build --mkdocs --module docforge\n\n# Wiki + library (each an independent MkDocs build)\ndoc-forge build --wiki --mkdocs --module docforge\n\n# Wiki only \u2014 no module required\ndoc-forge build --wiki --site-name docforge\n\n# MCP structured bundle\ndoc-forge build --mcp --module docforge\n
      "},{"location":"04_iterative_workflow/#what-a-build-does","title":"\ud83d\udd04 What a build does","text":"
      1. Validates the requested modes (--mkdocs, --api, --wiki, --mcp).
      2. Generates library sources under docs/lib/** with MkDocsRenderer.
      3. Generates API sources under docs/api/** when --api is given.
      4. Derives the wiki navigation from docs/wiki/**.
      5. Writes one MkDocs config per site kind (docs/mkdocs.{lib,api,wiki}.yml), re-rooting navigation paths to each kind's docs_dir.
      6. Runs mkdocs build once per config, emitting self-contained sites site/lib/, site/api/, and site/wiki/.
      "},{"location":"04_iterative_workflow/#explore-the-sites","title":"\ud83e\udded Explore the sites","text":"
      doc-forge build --wiki --mkdocs --module docforge\ndoc-forge serve --wiki       # serves site preview from docs/mkdocs.wiki.yml\ndoc-forge serve --lib\ndoc-forge serve --api\n# or target any config directly:\ndoc-forge serve --mkdocs --mkdocs-yml docs/mkdocs.wiki.yml\n
      "},{"location":"04_iterative_workflow/#serve-the-mcp-bundle","title":"\ud83d\udce6 Serve the MCP bundle","text":"
      doc-forge build --mcp --module docforge\ndoc-forge serve --mcp --module docforge\n
      "},{"location":"04_iterative_workflow/#related","title":"Related","text":""},{"location":"05_development/01_environment/","title":"Environment Setup","text":""},{"location":"05_development/01_environment/#create-the-environment","title":"\ud83d\ude80 Create the environment","text":"
      python -m venv .venv\n.venv\\Scripts\\activate\npip install -e .\n

      Requires Python 3.10+ (per pyproject.toml).

      "},{"location":"05_development/01_environment/#dependencies","title":"\ud83d\udce6 Dependencies","text":"

      Development extras include:

      "},{"location":"05_development/01_environment/#related","title":"Related","text":""},{"location":"05_development/02_quality_gates/","title":"Quality Gates","text":"

      Run all checks before pushing:

      "},{"location":"05_development/02_quality_gates/#commands","title":"\ud83d\ude80 Commands","text":"
      .venv\\Scripts\\python.exe -m pytest\n.venv\\Scripts\\python.exe -m ruff check docforge tests\n.venv\\Scripts\\python.exe -m black --check docforge tests\n.venv\\Scripts\\python.exe -m mypy docforge\n.venv\\Scripts\\pydoclint.exe docforge\n
      "},{"location":"05_development/02_quality_gates/#test-layout","title":"\ud83d\udcc1 Test layout","text":"Path Covers tests/nav/ Nav spec, resolver, wiki nav tests/cli/ Build command flows and modes tests/renderers/ MkDocs / MCP rendering

      CLI tests use the cli_runner fixture with mock_mkdocs_build and mock_mkdocs_load_config so they exercise the full flow without invoking a real MkDocs build.

      "},{"location":"05_development/02_quality_gates/#related","title":"Related","text":""},{"location":"05_development/03_gsdfc_guide/","title":"GSDFC Docstring Guide","text":"

      This page is the practical companion to the authoritative GSDFC specification in the docforge/__init__.py package docstring. It describes how to write docstrings that render correctly in MkDocs and stay machine-parseable by doc-forge, MkDocs, and MCP clients.

      "},{"location":"05_development/03_gsdfc_guide/#overview","title":"\ud83e\udded Overview","text":""},{"location":"05_development/03_gsdfc_guide/#module-docstrings","title":"\ud83d\udce6 Module docstrings","text":"

      Modules use Markdown headings and --- separators.

      Recommended sections:

      "},{"location":"05_development/03_gsdfc_guide/#class-docstrings","title":"\ud83d\udce6 Class docstrings","text":"

      Recommended sections, in order:

      "},{"location":"05_development/03_gsdfc_guide/#function-and-method-docstrings","title":"\ud83d\udce6 Function and method docstrings","text":"

      Recommended section order:

      1. Args:
      2. Returns:
      3. Raises:
      4. Yields:
      5. Notes:
      6. Example:

      Formatting rules:

      "},{"location":"05_development/03_gsdfc_guide/#property-docstrings","title":"\ud83d\udce6 Property docstrings","text":"

      Properties document their return values with a Returns: section and, when meaningful, an Example:.

      "},{"location":"05_development/03_gsdfc_guide/#example","title":"\ud83d\ude80 Example","text":"
      def process(foo: Foo, multiplier: int) -> int:\n    \"\"\"Process a Foo instance.\n\n    Args:\n        foo (Foo):\n            Foo instance to process.\n\n        multiplier (int):\n            Value used to scale foo.\n\n    Returns:\n        int:\n            Processed result.\n\n    Raises:\n        ValueError:\n            If multiplier is negative.\n\n    Example:\n        Process foo:\n\n            ```python\n            foo = Foo(\"example\", value=10)\n            result = process(foo, multiplier=2)\n            print(result)\n            ```\n    \"\"\"\n
      "},{"location":"05_development/03_gsdfc_guide/#keeping-stubs-in-sync","title":"\ud83d\udd04 Keeping stubs in sync","text":"

      Every .py module ships a matching .pyi stub. When a signature or a public symbol changes, update both files. Signature annotations in the stub must match the implementation.

      "},{"location":"05_development/03_gsdfc_guide/#enforcement","title":"\ud83d\udee1\ufe0f Enforcement","text":"

      pydoclint (Google style) runs in CI and verifies that Args:/Returns: sections match function signatures, including types.

      "},{"location":"05_development/03_gsdfc_guide/#related","title":"Related","text":""},{"location":"05_development/04_mcp_guide/","title":"MCP Guide","text":"

      Doc-forge can export a machine-readable MCP bundle from a project's GSDFC docstrings and serve that bundle over the Model Context Protocol (MCP). The bundle is self-contained: readers can derive the full API reference \u2014 signatures, docstrings, and structure \u2014 for the documented project.

      "},{"location":"05_development/04_mcp_guide/#building-the-bundle","title":"\ud83d\ude80 Building the bundle","text":"
      doc-forge build --mcp --module docforge\n

      This writes structured JSON into docs/mcp/:

      "},{"location":"05_development/04_mcp_guide/#serving-the-bundle","title":"\ud83d\ude80 Serving the bundle","text":"
      doc-forge serve --mcp --module docforge\n

      The MCPServer (in docforge/servers/mcp_server.py) exposes:

      Resource Description docs://index Project metadata docs://nav Navigation structure docs://modules/{module} Individual module documentation

      The server also registers a single diagnostic tool, ping, and is read-only. Missing resources are returned as structured error dictionaries rather than exceptions. The default transport is streamable-http; stdio and sse are supported via MCPServer.run.

      "},{"location":"05_development/04_mcp_guide/#bundle-contents","title":"\ud83d\udce6 Bundle contents","text":"

      Each module resource contains:

      Because the bundle is generated from docstrings, the quality of the bundle equals the quality of the project's GSDFC docstrings. For docforge itself, the GSDFC specification is carried in modules/docforge.json via the docforge/__init__.py package docstring, making the bundle self-documenting.

      "},{"location":"05_development/04_mcp_guide/#related","title":"Related","text":""},{"location":"05_development/05_mkdocs_configs/","title":"MkDocs Configuration Model","text":"

      Each documentation kind (lib, api, wiki) is built by its own MkDocs site. A repo that documents kind {kind} carries a config at docs/mkdocs.{kind}.yml that sets docs_dir to the kind's source directory and site_dir to ../site/{kind}.

      "},{"location":"05_development/05_mkdocs_configs/#file-wins","title":"\ud83d\udcc4 File wins","text":"

      docs/mkdocs.{kind}.yml is a repo-owned file, not a build byproduct:

      Because a present file is never rewritten, rerunning a build is a no-op for versioned configs: the working tree stays clean.

      "},{"location":"05_development/05_mkdocs_configs/#templates","title":"\ud83e\udde9 Templates","text":"

      The built-in defaults live in docforge/templates/:

      File Role mkdocs.common.yml Shared theme + markdown extensions mkdocs.lib.yml mkdocstrings handler for library reference mkdocs.api.yml Swagger/OpenAPI plugins and API-side features mkdocs.wiki.yml Wiki look: horizontal navigation.tabs header, blue grey/teal palette, Roboto

      A per-kind config is generated by deep-merging the common template with the kind fragment, then filling in generation-time values (site_name, docs_dir, site_dir, nav, API site_description/site_author, and the theme icon from docforge.nav.yml). Pass --template <path> to replace the built-in templates entirely.

      "},{"location":"05_development/05_mkdocs_configs/#supported-layouts","title":"\ud83c\udfd7\ufe0f Supported layouts","text":"

      Commit docs/mkdocs.{kind}.yml so served docs are reproducible from source.

      "},{"location":"05_development/05_mkdocs_configs/#related","title":"Related","text":""}]} \ No newline at end of file diff --git a/doc-forge/wiki/sitemap.xml.gz b/doc-forge/wiki/sitemap.xml.gz index 2984a5c0604425d6c75a5222b5179590ee6a2ad7..01465253604ef76b3b2b517f1166919160e58317 100644 GIT binary patch delta 13 Ucmb=gXP58h;ArStF_FCj03F=~f&c&j delta 13 Ucmb=gXP58h;9#&^K9Riw02xFBumAu6 diff --git a/mcp/doc-forge/modules/docforge.cli.commands.json b/mcp/doc-forge/modules/docforge.cli.commands.json index dcec1a1..79af154 100644 --- a/mcp/doc-forge/modules/docforge.cli.commands.json +++ b/mcp/doc-forge/modules/docforge.cli.commands.json @@ -557,21 +557,21 @@ "name": "build", "kind": "function", "path": "docforge.cli.commands.build", - "signature": "", - "docstring": "Build documentation artifacts.\n\nThis command runs the full documentation pipeline: it loads Python\nmodules, generates renderer-specific documentation sources, and\noptionally builds the final output.\n\nDepending on the selected options, the build can target:\n\n- A lib MkDocs site (`--mkdocs`) for library reference docs\n- A swagger-enabled API MkDocs site (`--api`) built from an OpenAPI spec\n- A wiki MkDocs site (`--wiki`) built from hand-written markdown\n- MCP structured documentation resources (`--mcp`)\n\nEach enabled site kind produces its own MkDocs configuration\n(`docs/mkdocs.{kind}.yml`) and its own build (`site/{kind}`).\n\nNotes:\n - At least one of `--mcp`, `--mkdocs`, `--wiki`, or `--api` must be\n provided.\n - `--mkdocs`, `--api`, and `--wiki` emit independent MkDocs builds,\n while `--mcp` emits a machine-readable bundle.\n\nArgs:\n mcp (bool):\n Enable MCP documentation generation.\n\n mkdocs (bool):\n Enable the lib MkDocs documentation generation.\n\n api (bool):\n Enable API documentation generation from an OpenAPI spec.\n\n wiki (bool):\n Build a hand-written wiki directory as its own MkDocs site.\n\n module_is_source (bool):\n Treat the specified module directory as the project root.\n\n module (str | None):\n Python module import path to document.\n\n openapi_spec (Path | None):\n Path to the OpenAPI JSON specification used for API docs.\n\n project_name (str | None):\n Optional override for the project name.\n\n site_name (str | None):\n Display name for the lib and wiki MkDocs sites.\n\n docs_dir (Path):\n Shared documentation root used for generated sources.\n wiki_dir (Path):\n Directory containing hand-written wiki markdown files.\n\n nav_file (Path):\n Path to the navigation specification file.\n\n template (Path | None):\n Optional custom MkDocs configuration template.\n\n out_dir (Path):\n Output directory for generated MCP resources.\n\nRaises:\n click.UsageError:\n If required options are missing or conflicting." + "signature": "", + "docstring": "Build documentation artifacts.\n\nThis command runs the full documentation pipeline: it loads Python\nmodules, generates renderer-specific documentation sources, and\noptionally builds the final output.\n\nDepending on the selected options, the build can target:\n\n- A lib MkDocs site (`--mkdocs`) for library reference docs\n- A swagger-enabled API MkDocs site (`--api`) built from an OpenAPI spec\n- A wiki MkDocs site (`--wiki`) built from hand-written markdown\n- MCP structured documentation resources (`--mcp`)\n\nEach enabled site kind produces its own MkDocs configuration\n(`docs/mkdocs.{kind}.yml`) and its own build (`site/{kind}`).\n\nNotes:\n - At least one of `--mcp`, `--mkdocs`, `--wiki`, or `--api` must be\n provided.\n - `--mkdocs`, `--api`, and `--wiki` emit independent MkDocs builds,\n while `--mcp` emits a machine-readable bundle.\n - Configuration files are generated only when absent; an existing\n `docs/mkdocs.{kind}.yml` is used as-is. Pass `--refresh` to\n rebaseline it from the templates.\n\nArgs:\n mcp (bool):\n Enable MCP documentation generation.\n\n mkdocs (bool):\n Enable the lib MkDocs documentation generation.\n\n api (bool):\n Enable API documentation generation from an OpenAPI spec.\n\n wiki (bool):\n Build a hand-written wiki directory as its own MkDocs site.\n\n refresh (bool):\n Regenerate ``docs/mkdocs.{kind}.yml`` from templates even when\n it already exists. By default, existing configs are used as-is.\n\n module_is_source (bool):\n Treat the specified module directory as the project root.\n\n module (str | None):\n Python module import path to document.\n\n openapi_spec (Path | None):\n Path to the OpenAPI JSON specification used for API docs.\n\n project_name (str | None):\n Optional override for the project name.\n\n site_name (str | None):\n Display name for the lib and wiki MkDocs sites.\n\n docs_dir (Path):\n Shared documentation root used for generated sources.\n wiki_dir (Path):\n Directory containing hand-written wiki markdown files.\n\n nav_file (Path):\n Path to the navigation specification file.\n\n template (Path | None):\n Optional custom MkDocs configuration template.\n\n out_dir (Path):\n Output directory for generated MCP resources.\n\nRaises:\n click.UsageError:\n If required options are missing or conflicting." }, "serve": { "name": "serve", "kind": "function", "path": "docforge.cli.commands.serve", - "signature": "", + "signature": "", "docstring": "Serve generated documentation locally.\n\nDepending on the selected mode, this command starts either:\n\n- A MkDocs development server for browsing a site, or\n- An MCP server exposing structured documentation resources\n\nThe kind flags (`--lib`, `--api`, `--wiki`) select the generated\nper-kind config (`docs/mkdocs.{kind}.yml`); `--mkdocs` serves the config\npassed via `--mkdocs-yml`.\n\nArgs:\n mcp (bool):\n Serve documentation using the MCP server.\n\n mkdocs (bool):\n Serve the MkDocs development site from ``--mkdocs-yml``.\n\n lib (bool):\n Serve the lib MkDocs site.\n\n api (bool):\n Serve the API MkDocs site.\n\n wiki (bool):\n Serve the wiki MkDocs site.\n\n module (str | None):\n Python module import path to serve via MCP.\n\n mkdocs_yml (Path):\n Path to the MkDocs configuration file.\n\n out_dir (Path):\n Root directory containing MCP documentation resources.\n\nRaises:\n click.UsageError:\n If invalid or conflicting options are provided." }, "tree": { "name": "tree", "kind": "function", "path": "docforge.cli.commands.tree", - "signature": "", + "signature": "", "docstring": "Display the documentation object tree for a module.\n\nThis command introspects the specified module and prints a\nhierarchical representation of the discovered documentation\nobjects, including modules, classes, functions, and members.\n\nArgs:\n module (str):\n Python module import path to introspect.\n\n project_name (str | None):\n Optional name to display as the project root." }, "Group": { diff --git a/mcp/doc-forge/modules/docforge.cli.json b/mcp/doc-forge/modules/docforge.cli.json index 75cc4e9..be6964a 100644 --- a/mcp/doc-forge/modules/docforge.cli.json +++ b/mcp/doc-forge/modules/docforge.cli.json @@ -689,21 +689,21 @@ "name": "build", "kind": "function", "path": "docforge.cli.commands.build", - "signature": "", - "docstring": "Build documentation artifacts.\n\nThis command runs the full documentation pipeline: it loads Python\nmodules, generates renderer-specific documentation sources, and\noptionally builds the final output.\n\nDepending on the selected options, the build can target:\n\n- A lib MkDocs site (`--mkdocs`) for library reference docs\n- A swagger-enabled API MkDocs site (`--api`) built from an OpenAPI spec\n- A wiki MkDocs site (`--wiki`) built from hand-written markdown\n- MCP structured documentation resources (`--mcp`)\n\nEach enabled site kind produces its own MkDocs configuration\n(`docs/mkdocs.{kind}.yml`) and its own build (`site/{kind}`).\n\nNotes:\n - At least one of `--mcp`, `--mkdocs`, `--wiki`, or `--api` must be\n provided.\n - `--mkdocs`, `--api`, and `--wiki` emit independent MkDocs builds,\n while `--mcp` emits a machine-readable bundle.\n\nArgs:\n mcp (bool):\n Enable MCP documentation generation.\n\n mkdocs (bool):\n Enable the lib MkDocs documentation generation.\n\n api (bool):\n Enable API documentation generation from an OpenAPI spec.\n\n wiki (bool):\n Build a hand-written wiki directory as its own MkDocs site.\n\n module_is_source (bool):\n Treat the specified module directory as the project root.\n\n module (str | None):\n Python module import path to document.\n\n openapi_spec (Path | None):\n Path to the OpenAPI JSON specification used for API docs.\n\n project_name (str | None):\n Optional override for the project name.\n\n site_name (str | None):\n Display name for the lib and wiki MkDocs sites.\n\n docs_dir (Path):\n Shared documentation root used for generated sources.\n wiki_dir (Path):\n Directory containing hand-written wiki markdown files.\n\n nav_file (Path):\n Path to the navigation specification file.\n\n template (Path | None):\n Optional custom MkDocs configuration template.\n\n out_dir (Path):\n Output directory for generated MCP resources.\n\nRaises:\n click.UsageError:\n If required options are missing or conflicting." + "signature": "", + "docstring": "Build documentation artifacts.\n\nThis command runs the full documentation pipeline: it loads Python\nmodules, generates renderer-specific documentation sources, and\noptionally builds the final output.\n\nDepending on the selected options, the build can target:\n\n- A lib MkDocs site (`--mkdocs`) for library reference docs\n- A swagger-enabled API MkDocs site (`--api`) built from an OpenAPI spec\n- A wiki MkDocs site (`--wiki`) built from hand-written markdown\n- MCP structured documentation resources (`--mcp`)\n\nEach enabled site kind produces its own MkDocs configuration\n(`docs/mkdocs.{kind}.yml`) and its own build (`site/{kind}`).\n\nNotes:\n - At least one of `--mcp`, `--mkdocs`, `--wiki`, or `--api` must be\n provided.\n - `--mkdocs`, `--api`, and `--wiki` emit independent MkDocs builds,\n while `--mcp` emits a machine-readable bundle.\n - Configuration files are generated only when absent; an existing\n `docs/mkdocs.{kind}.yml` is used as-is. Pass `--refresh` to\n rebaseline it from the templates.\n\nArgs:\n mcp (bool):\n Enable MCP documentation generation.\n\n mkdocs (bool):\n Enable the lib MkDocs documentation generation.\n\n api (bool):\n Enable API documentation generation from an OpenAPI spec.\n\n wiki (bool):\n Build a hand-written wiki directory as its own MkDocs site.\n\n refresh (bool):\n Regenerate ``docs/mkdocs.{kind}.yml`` from templates even when\n it already exists. By default, existing configs are used as-is.\n\n module_is_source (bool):\n Treat the specified module directory as the project root.\n\n module (str | None):\n Python module import path to document.\n\n openapi_spec (Path | None):\n Path to the OpenAPI JSON specification used for API docs.\n\n project_name (str | None):\n Optional override for the project name.\n\n site_name (str | None):\n Display name for the lib and wiki MkDocs sites.\n\n docs_dir (Path):\n Shared documentation root used for generated sources.\n wiki_dir (Path):\n Directory containing hand-written wiki markdown files.\n\n nav_file (Path):\n Path to the navigation specification file.\n\n template (Path | None):\n Optional custom MkDocs configuration template.\n\n out_dir (Path):\n Output directory for generated MCP resources.\n\nRaises:\n click.UsageError:\n If required options are missing or conflicting." }, "serve": { "name": "serve", "kind": "function", "path": "docforge.cli.commands.serve", - "signature": "", + "signature": "", "docstring": "Serve generated documentation locally.\n\nDepending on the selected mode, this command starts either:\n\n- A MkDocs development server for browsing a site, or\n- An MCP server exposing structured documentation resources\n\nThe kind flags (`--lib`, `--api`, `--wiki`) select the generated\nper-kind config (`docs/mkdocs.{kind}.yml`); `--mkdocs` serves the config\npassed via `--mkdocs-yml`.\n\nArgs:\n mcp (bool):\n Serve documentation using the MCP server.\n\n mkdocs (bool):\n Serve the MkDocs development site from ``--mkdocs-yml``.\n\n lib (bool):\n Serve the lib MkDocs site.\n\n api (bool):\n Serve the API MkDocs site.\n\n wiki (bool):\n Serve the wiki MkDocs site.\n\n module (str | None):\n Python module import path to serve via MCP.\n\n mkdocs_yml (Path):\n Path to the MkDocs configuration file.\n\n out_dir (Path):\n Root directory containing MCP documentation resources.\n\nRaises:\n click.UsageError:\n If invalid or conflicting options are provided." }, "tree": { "name": "tree", "kind": "function", "path": "docforge.cli.commands.tree", - "signature": "", + "signature": "", "docstring": "Display the documentation object tree for a module.\n\nThis command introspects the specified module and prints a\nhierarchical representation of the discovered documentation\nobjects, including modules, classes, functions, and members.\n\nArgs:\n module (str):\n Python module import path to introspect.\n\n project_name (str | None):\n Optional name to display as the project root." }, "Group": { diff --git a/mcp/doc-forge/modules/docforge.json b/mcp/doc-forge/modules/docforge.json index 17b68ad..99ac7a0 100644 --- a/mcp/doc-forge/modules/docforge.json +++ b/mcp/doc-forge/modules/docforge.json @@ -2,7 +2,7 @@ "module": "docforge", "content": { "path": "docforge", - "docstring": "# Summary\n\nRenderer-agnostic Python documentation compiler that converts Python docstrings\ninto structured documentation for both humans (MkDocs) and machines (MCP / AI agents).\n\n`doc-forge` statically analyzes source code, builds a semantic model of modules,\nclasses, functions, and attributes, and renders that model into documentation\noutputs without executing user code.\n\n---\n\n# Installation\n\nInstall using pip:\n\n```bash\npip install doc-forge\n```\n\n---\n\n# CLI usage\n\nEach site kind (`lib`, `api`, `wiki`) is built independently into `site/{kind}`.\n\n## Build the library reference from a Python package:\n\n```bash\ndoc-forge build --mkdocs --module my_package\n```\n\n## Build the API reference from an OpenAPI spec:\n\n```bash\ndoc-forge build --api --openapi-spec spec.json\n```\n\n## Build the hand-written wiki:\n\n```bash\ndoc-forge build --wiki --site-name my_package\n```\n\n## Generate MCP JSON documentation:\n\n```bash\ndoc-forge build --mcp --module my_package\n```\n\n## Build several kinds in one pass:\n\n```bash\ndoc-forge build --mcp --mkdocs --wiki --module my_package\n```\n\nEach enabled kind gets its own MkDocs config (`docs/mkdocs.{lib,api,wiki}.yml`)\nand its own site under `site/`.\n\n## Serve a site locally:\n\n```bash\ndoc-forge serve --wiki # preview from docs/mkdocs.wiki.yml\ndoc-forge serve --lib\ndoc-forge serve --api\n# or any config directly:\ndoc-forge serve --mkdocs --mkdocs-yml docs/mkdocs.wiki.yml\n```\n\n## Serve MCP locally:\n\n```bash\ndoc-forge serve --mcp --module my_package\n```\n\n---\n\n# Core concepts\n\n## Loader\nExtracts symbols, signatures, and docstrings using static analysis.\n\n## Semantic model\nStructured, renderer-agnostic representation of the API.\n\n## Renderer\nConverts the semantic model into output formats such as MkDocs or MCP JSON.\n\n## Symbol\nAny documentable object\n\n- module\n- class\n- function\n- method\n- property\n- attribute\n\n---\n\n# Architecture\n\n`doc-forge` follows a compiler architecture:\n\n## Front-end:\n\nStatic analysis of modules, classes, functions, type hints, and docstrings.\n\n## Middle-end:\n\nBuilds a semantic model describing symbols and relationships.\n\n## Back-end:\n\nRenders documentation using interchangeable renderers.\n\nThis architecture ensures deterministic documentation generation.\n\n---\n\n# Rendering pipeline\n\nTypical flow:\n\n Python package\n |\n Loader (static analysis)\n |\n Semantic model\n |\n Renderer\n |\n MkDocs site or MCP JSON\n\n---\n\n# Google-Styled Doc-Forge Convention (GSDFC)\n\nGSDFC defines how docstrings must be written so they render correctly in MkDocs and remain machine-parsable by doc-forge and AI tooling.\n\n- Docstrings are the single source of truth.\n- `doc-forge` compiles docstrings but does not generate documentation content.\n- Documentation follows the Python import hierarchy.\n- Every public symbol should have a complete and accurate docstring.\n\n---\n\n## General rules\n\n- Use **Markdown headings** at package and module level.\n- Use **Google-style structured sections** at class, function, and method level.\n- Use type hints in signatures.\n- Use parenthesized types in prose entries (`name (Type):`) that match the\n signature types. This keeps docstrings self-contained and machine-parseable.\n- Write summaries in imperative form.\n- Sections are separated by `---`\n\n---\n\n# Notes subsection grouping\n\nGroup related information using labeled subsections.\n\nExample:\n\n Notes:\n **Guarantees:**\n\n - deterministic behavior\n\n **Lifecycle:**\n\n - created during initialization\n - reused across executions\n\n **Thread safety:**\n\n - safe for concurrent reads\n\n---\n\n# Example formatting\n\n- Use indentation for examples.\n- Indent section contents using four spaces.\n- Use code blocks for example code.\n\nExample:\n Single example:\n\n Example:\n\n ```python\n foo = Foo(\"example\")\n process(foo, multiplier=2)\n ```\n\n Multiple examples:\n\n Example:\n Create foo:\n\n ```python\n foo = Foo(\"example\")\n ```\n\n Run engine:\n\n ```python\n engine = BarEngine([foo])\n engine.run()\n ```\n\nAvoid fenced code blocks inside argument descriptions and other prose lines.\n\nInside `Example:` sections, fenced `python` code blocks are allowed and must be\nindented four spaces, matching the examples below.\n\n---\n\n# Separator rules\n\nUse horizontal separators only at docstring root level to separate sections:\n\n```markdown\n---\n```\n\nAllowed locations:\n\n- package docstrings\n- module docstrings\n- major documentation sections\n\nDo not use separators inside code sections.\n\n---\n\n# Package docstrings\n\nPackage docstrings act as the documentation home page.\n\nRecommended sections:\n\n # Summary\n # Installation\n # Quick start\n # CLI usage\n # Core concepts\n # Architecture\n # Rendering pipeline\n # Examples\n # Notes\n\nExample:\n Package Doc String:\n\n '''\n # Summary\n\n Foo-bar processing framework.\n\n Provides tools for defining Foo objects and executing Bar pipelines.\n\n ---\n\n # Installation\n\n ```bash\n pip install foo-bar\n ```\n\n ---\n\n # Quick start\n\n ```python\n from foobar import Foo, BarEngine\n\n foo = Foo(\"example\")\n engine = BarEngine([foo])\n\n result = engine.run()\n ```\n\n ---\n '''\n\n---\n\n# Module docstrings\n\nModule docstrings describe a subsystem.\n\nRecommended sections:\n\n # Summary\n # Examples\n # Notes\n\nExample:\n Module Doc String:\n\n '''\n # Summary\n\n Foo execution subsystem.\n\n Provides utilities for executing Foo objects through Bar stages.\n\n ---\n\n Example:\n\n ```python\n from foobar.engine import BarEngine\n from foobar.foo import Foo\n\n foo = Foo(\"example\")\n\n engine = BarEngine([foo])\n engine.run()\n ```\n\n ---\n '''\n\n---\n\n# Class docstrings\n\nClass docstrings define object responsibility, lifecycle, and attributes.\n\nRecommended sections:\n\n Attributes:\n Notes:\n Example:\n Raises:\n\nExample:\n Simple Foo:\n\n ```python\n class Foo:\n '''\n Represents a unit of work.\n\n Attributes:\n name (str):\n Identifier of the foo instance.\n\n value (int):\n Numeric value associated with foo.\n\n Notes:\n Guarantees:\n\n - instances are immutable after creation\n\n Lifecycle:\n\n - create instance\n - pass to processing engine\n\n Example:\n Create and inspect a Foo:\n\n ```python\n foo = Foo(\"example\", value=42)\n print(foo.name)\n ```\n '''\n ```\n\n Complex Bar:\n\n ```python\n class BarEngine:\n '''\n Executes Foo objects through Bar stages.\n\n Attributes:\n foos (tuple[Foo, ...]):\n Foo instances managed by the engine.\n\n Notes:\n Guarantees:\n\n - deterministic execution order\n\n Example:\n Run engine:\n\n ```python\n foo1 = Foo(\"a\")\n foo2 = Foo(\"b\")\n\n engine = BarEngine([foo1, foo2])\n engine.run()\n ```\n '''\n ```\n\n---\n\n# Function and method docstrings\n\nFunction docstrings define API contracts.\n\nRecommended sections:\n\n Args:\n Returns:\n Raises:\n Yields:\n Notes:\n Example:\n\nExample:\n Simple process method:\n\n ```python\n def process(foo: Foo, multiplier: int) -> int:\n '''\n Process a Foo instance.\n\n Args:\n foo (Foo):\n Foo instance to process.\n\n multiplier (int):\n Value used to scale foo.\n\n Returns:\n int:\n Processed result.\n\n Raises:\n ValueError:\n If multiplier is negative.\n\n Notes:\n Guarantees:\n\n - foo is not modified\n\n Example:\n Process foo:\n\n ```python\n foo = Foo(\"example\", value=10)\n\n result = process(foo, multiplier=2)\n print(result)\n ```\n '''\n ```\n\n Multiple Examples:\n\n ```python\n def combine(foo_a: Foo, foo_b: Foo) -> Foo:\n '''\n Combine two Foo instances.\n\n Args:\n foo_a (Foo):\n First foo.\n\n foo_b (Foo):\n Second foo.\n\n Returns:\n Foo:\n Combined foo.\n\n Example:\n Basic usage:\n\n ```python\n foo1 = Foo(\"a\")\n foo2 = Foo(\"b\")\n\n combined = combine(foo1, foo2)\n ```\n\n Pipeline usage:\n\n ```python\n engine = BarEngine([foo1, foo2])\n engine.run()\n ```\n '''\n ```\n\n---\n\n# Property docstrings\n\nProperties must document return values.\n\nExample:\n Property Doc String:\n\n ```python\n @property\n def foos(self) -> tuple[Foo, ...]:\n '''\n Return contained Foo instances.\n\n Returns:\n tuple[Foo, ...]:\n Stored foo objects.\n\n Example:\n ```python\n container = FooContainer()\n\n foos = container.foos\n ```\n '''\n ```\n\n---\n\n# Attribute documentation\n\nDocument attributes in class docstrings using `Attributes:`.\n\nExample:\n Attribute Doc String:\n\n ```python\n '''\n Represents a processing stage.\n\n Attributes:\n id (str):\n Unique identifier.\n\n enabled (bool):\n Whether the stage is active.\n '''\n ```\n\n---\n\n# Parsing guarantees\n\nGSDFC ensures doc-forge can deterministically extract:\n\n- symbol kind (module, class, function, property, attribute)\n- symbol name\n- parameters\n- return values\n- attributes\n- examples\n- structured Notes subsections\n\nThis enables:\n\n- reliable MkDocs rendering\n- deterministic MCP export\n- accurate AI semantic interpretation\n\n---\n\nNotes:\n - doc-forge never executes analyzed modules.\n - Documentation is generated entirely through static analysis.", + "docstring": "# Summary\n\nRenderer-agnostic Python documentation compiler that converts Python docstrings\ninto structured documentation for both humans (MkDocs) and machines (MCP / AI agents).\n\n`doc-forge` statically analyzes source code, builds a semantic model of modules,\nclasses, functions, and attributes, and renders that model into documentation\noutputs without executing user code.\n\n---\n\n# Installation\n\nInstall using pip:\n\n```bash\npip install doc-forge\n```\n\n---\n\n# CLI usage\n\nEach site kind (`lib`, `api`, `wiki`) is built independently into `site/{kind}`.\n\n## Build the library reference from a Python package:\n\n```bash\ndoc-forge build --mkdocs --module my_package\n```\n\n## Build the API reference from an OpenAPI spec:\n\n```bash\ndoc-forge build --api --openapi-spec spec.json\n```\n\n## Build the hand-written wiki:\n\n```bash\ndoc-forge build --wiki --site-name my_package\n```\n\n## Generate MCP JSON documentation:\n\n```bash\ndoc-forge build --mcp --module my_package\n```\n\n## Build several kinds in one pass:\n\n```bash\ndoc-forge build --mcp --mkdocs --wiki --module my_package\n```\n\nEach enabled kind gets its own MkDocs config (`docs/mkdocs.{lib,api,wiki}.yml`)\nand its own site under `site/`.\n\n## Serve a site locally:\n\n```bash\ndoc-forge serve --wiki # preview from docs/mkdocs.wiki.yml\ndoc-forge serve --lib\ndoc-forge serve --api\n# or any config directly:\ndoc-forge serve --mkdocs --mkdocs-yml docs/mkdocs.wiki.yml\n```\n\n## Serve MCP locally:\n\n```bash\ndoc-forge serve --mcp --module my_package\n```\n\n---\n\n# Core concepts\n\n## Loader\nExtracts symbols, signatures, and docstrings using static analysis.\n\n## Semantic model\nStructured, renderer-agnostic representation of the API.\n\n## Renderer\nConverts the semantic model into output formats such as MkDocs or MCP JSON.\n\n## Symbol\nAny documentable object\n\n- module\n- class\n- function\n- method\n- property\n- attribute\n\n---\n\n# Architecture\n\n`doc-forge` follows a compiler architecture:\n\n## Front-end:\n\nStatic analysis of modules, classes, functions, type hints, and docstrings.\n\n## Middle-end:\n\nBuilds a semantic model describing symbols and relationships.\n\n## Back-end:\n\nRenders documentation using interchangeable renderers.\n\nThis architecture ensures deterministic documentation generation.\n\n---\n\n# Rendering pipeline\n\nTypical flow:\n\n Python package\n |\n Loader (static analysis)\n |\n Semantic model\n |\n Renderer\n |\n MkDocs site or MCP JSON\n\n---\n\n# Google-Styled Doc-Forge Convention (GSDFC)\n\nGSDFC defines how docstrings must be written so they render correctly in MkDocs and remain machine-parsable by doc-forge and AI tooling.\n\n- Docstrings are the single source of truth.\n- `doc-forge` compiles docstrings but does not generate documentation content.\n- Documentation follows the Python import hierarchy.\n- Every public symbol should have a complete and accurate docstring.\n\n---\n\n## General rules\n\n- Use **Markdown headings** at package and module level.\n- Use **Google-style structured sections** at class, function, and method level.\n- Use type hints in signatures.\n- Use parenthesized types in prose entries (`name (Type):`) that match the\n signature types. This keeps docstrings self-contained and machine-parseable.\n- Write summaries in imperative form.\n- Sections are separated by `---`\n\n---\n\n# Notes subsection grouping\n\nGroup related information using labeled subsections.\n\nExample:\n\n Notes:\n **Guarantees:**\n\n - deterministic behavior\n\n **Lifecycle:**\n\n - created during initialization\n - reused across executions\n\n **Thread safety:**\n\n - safe for concurrent reads\n\n---\n\n# Example formatting\n\n- Use indentation for examples.\n- Indent section contents using four spaces.\n- Use code blocks for example code.\n\nExample:\n Single example:\n\n Example:\n\n ```python\n foo = Foo(\"example\")\n process(foo, multiplier=2)\n ```\n\n Multiple examples:\n\n Example:\n Create foo:\n\n ```python\n foo = Foo(\"example\")\n ```\n\n Run engine:\n\n ```python\n engine = BarEngine([foo])\n engine.run()\n ```\n\nAvoid fenced code blocks inside argument descriptions and other prose lines.\n\nInside `Example:` sections, fenced `python` code blocks are allowed and must be\nindented four spaces, matching the examples below.\n\n---\n\n# Separator rules\n\nUse horizontal separators only at docstring root level to separate sections:\n\n```markdown\n---\n```\n\nAllowed locations:\n\n- package docstrings\n- module docstrings\n- major documentation sections\n\nDo not use separators inside code sections.\n\n---\n\n# Package docstrings\n\nPackage docstrings act as the documentation home page.\n\nRecommended sections:\n\n # Summary\n # Installation\n # Quick start\n # CLI usage\n # Core concepts\n # Architecture\n # Rendering pipeline\n # Examples\n # Notes\n\nExample:\n Package Doc String:\n\n '''\n # Summary\n\n Foo-bar processing framework.\n\n Provides tools for defining Foo objects and executing Bar pipelines.\n\n ---\n\n # Installation\n\n ```bash\n pip install foo-bar\n ```\n\n ---\n\n # Quick start\n\n ```python\n from foobar import Foo, BarEngine\n\n foo = Foo(\"example\")\n engine = BarEngine([foo])\n\n result = engine.run()\n ```\n\n ---\n '''\n\n---\n\n# Module docstrings\n\nModule docstrings describe a subsystem.\n\nRecommended sections:\n\n # Summary\n # Examples\n # Notes\n\nExample:\n Module Doc String:\n\n '''\n # Summary\n\n Foo execution subsystem.\n\n Provides utilities for executing Foo objects through Bar stages.\n\n ---\n\n Example:\n\n ```python\n from foobar.engine import BarEngine\n from foobar.foo import Foo\n\n foo = Foo(\"example\")\n\n engine = BarEngine([foo])\n engine.run()\n ```\n\n ---\n '''\n\n---\n\n# Class docstrings\n\nClass docstrings define object responsibility, lifecycle, and attributes.\n\nRecommended sections:\n\n Attributes:\n Notes:\n Example:\n Raises:\n\nExample:\n Simple Foo:\n\n ```python\n class Foo:\n '''\n Represents a unit of work.\n\n Attributes:\n name (str):\n Identifier of the foo instance.\n\n value (int):\n Numeric value associated with foo.\n\n Notes:\n Guarantees:\n\n - instances are immutable after creation\n\n Lifecycle:\n\n - create instance\n - pass to processing engine\n\n Example:\n Create and inspect a Foo:\n\n ```python\n foo = Foo(\"example\", value=42)\n print(foo.name)\n ```\n '''\n ```\n\n Complex Bar:\n\n ```python\n class BarEngine:\n '''\n Executes Foo objects through Bar stages.\n\n Attributes:\n foos (tuple[Foo, ...]):\n Foo instances managed by the engine.\n\n Notes:\n Guarantees:\n\n - deterministic execution order\n\n Example:\n Run engine:\n\n ```python\n foo1 = Foo(\"a\")\n foo2 = Foo(\"b\")\n\n engine = BarEngine([foo1, foo2])\n engine.run()\n ```\n '''\n ```\n\n---\n\n# Function and method docstrings\n\nFunction docstrings define API contracts.\n\nRecommended sections:\n\n Args:\n Returns:\n Raises:\n Yields:\n Notes:\n Example:\n\nExample:\n Simple process method:\n\n ```python\n def process(foo: Foo, multiplier: int) -> int:\n '''\n Process a Foo instance.\n\n Args:\n foo (Foo):\n Foo instance to process.\n\n multiplier (int):\n Value used to scale foo.\n\n Returns:\n int:\n Processed result.\n\n Raises:\n ValueError:\n If multiplier is negative.\n\n Notes:\n Guarantees:\n\n - foo is not modified\n\n Example:\n Process foo:\n\n ```python\n foo = Foo(\"example\", value=10)\n\n result = process(foo, multiplier=2)\n print(result)\n ```\n '''\n ```\n\n Multiple Examples:\n\n ```python\n def combine(foo_a: Foo, foo_b: Foo) -> Foo:\n '''\n Combine two Foo instances.\n\n Args:\n foo_a (Foo):\n First foo.\n\n foo_b (Foo):\n Second foo.\n\n Returns:\n Foo:\n Combined foo.\n\n Example:\n Basic usage:\n\n ```python\n foo1 = Foo(\"a\")\n foo2 = Foo(\"b\")\n\n combined = combine(foo1, foo2)\n ```\n\n Pipeline usage:\n\n ```python\n engine = BarEngine([foo1, foo2])\n engine.run()\n ```\n '''\n ```\n\n---\n\n# Property docstrings\n\nProperties must document return values.\n\nExample:\n Property Doc String:\n\n ```python\n @property\n def foos(self) -> tuple[Foo, ...]:\n '''\n Return contained Foo instances.\n\n Returns:\n tuple[Foo, ...]:\n Stored foo objects.\n\n Example:\n ```python\n container = FooContainer()\n\n foos = container.foos\n ```\n '''\n ```\n\n---\n\n# Attribute documentation\n\nDocument attributes in class docstrings using `Attributes:`.\n\nExample:\n Attribute Doc String:\n\n ```python\n '''\n Represents a processing stage.\n\n Attributes:\n id (str):\n Unique identifier.\n\n enabled (bool):\n Whether the stage is active.\n '''\n ```\n\n---\n\n# Type parity (`.pyi` stubs and `py.typed`)\n\nDocumented APIs ship matching type information:\n\n- Each `.py` module has a synchronized `.pyi` stub in the same package.\n- Packages expose a `py.typed` marker so type checkers (and consumers)\n use the authored signatures instead of `Any`.\n- When signatures change, update the `.py` implementation and its `.pyi`\n stub together.\n- Doc-forge documents the docstrings in `.py`; the `.pyi` stub is the\n machine-consumable signature surface.\n\n---\n\n# Parsing guarantees\n\nGSDFC ensures doc-forge can deterministically extract:\n\n- symbol kind (module, class, function, property, attribute)\n- symbol name\n- parameters\n- return values\n- attributes\n- examples\n- structured Notes subsections\n\nThis enables:\n\n- reliable MkDocs rendering\n- deterministic MCP export\n- accurate AI semantic interpretation\n\n---\n\nNotes:\n - doc-forge never executes analyzed modules.\n - Documentation is generated entirely through static analysis.", "objects": { "GriffeLoader": { "name": "GriffeLoader", @@ -802,21 +802,21 @@ "name": "build", "kind": "function", "path": "docforge.cli.commands.build", - "signature": "", - "docstring": "Build documentation artifacts.\n\nThis command runs the full documentation pipeline: it loads Python\nmodules, generates renderer-specific documentation sources, and\noptionally builds the final output.\n\nDepending on the selected options, the build can target:\n\n- A lib MkDocs site (`--mkdocs`) for library reference docs\n- A swagger-enabled API MkDocs site (`--api`) built from an OpenAPI spec\n- A wiki MkDocs site (`--wiki`) built from hand-written markdown\n- MCP structured documentation resources (`--mcp`)\n\nEach enabled site kind produces its own MkDocs configuration\n(`docs/mkdocs.{kind}.yml`) and its own build (`site/{kind}`).\n\nNotes:\n - At least one of `--mcp`, `--mkdocs`, `--wiki`, or `--api` must be\n provided.\n - `--mkdocs`, `--api`, and `--wiki` emit independent MkDocs builds,\n while `--mcp` emits a machine-readable bundle.\n\nArgs:\n mcp (bool):\n Enable MCP documentation generation.\n\n mkdocs (bool):\n Enable the lib MkDocs documentation generation.\n\n api (bool):\n Enable API documentation generation from an OpenAPI spec.\n\n wiki (bool):\n Build a hand-written wiki directory as its own MkDocs site.\n\n module_is_source (bool):\n Treat the specified module directory as the project root.\n\n module (str | None):\n Python module import path to document.\n\n openapi_spec (Path | None):\n Path to the OpenAPI JSON specification used for API docs.\n\n project_name (str | None):\n Optional override for the project name.\n\n site_name (str | None):\n Display name for the lib and wiki MkDocs sites.\n\n docs_dir (Path):\n Shared documentation root used for generated sources.\n wiki_dir (Path):\n Directory containing hand-written wiki markdown files.\n\n nav_file (Path):\n Path to the navigation specification file.\n\n template (Path | None):\n Optional custom MkDocs configuration template.\n\n out_dir (Path):\n Output directory for generated MCP resources.\n\nRaises:\n click.UsageError:\n If required options are missing or conflicting." + "signature": "", + "docstring": "Build documentation artifacts.\n\nThis command runs the full documentation pipeline: it loads Python\nmodules, generates renderer-specific documentation sources, and\noptionally builds the final output.\n\nDepending on the selected options, the build can target:\n\n- A lib MkDocs site (`--mkdocs`) for library reference docs\n- A swagger-enabled API MkDocs site (`--api`) built from an OpenAPI spec\n- A wiki MkDocs site (`--wiki`) built from hand-written markdown\n- MCP structured documentation resources (`--mcp`)\n\nEach enabled site kind produces its own MkDocs configuration\n(`docs/mkdocs.{kind}.yml`) and its own build (`site/{kind}`).\n\nNotes:\n - At least one of `--mcp`, `--mkdocs`, `--wiki`, or `--api` must be\n provided.\n - `--mkdocs`, `--api`, and `--wiki` emit independent MkDocs builds,\n while `--mcp` emits a machine-readable bundle.\n - Configuration files are generated only when absent; an existing\n `docs/mkdocs.{kind}.yml` is used as-is. Pass `--refresh` to\n rebaseline it from the templates.\n\nArgs:\n mcp (bool):\n Enable MCP documentation generation.\n\n mkdocs (bool):\n Enable the lib MkDocs documentation generation.\n\n api (bool):\n Enable API documentation generation from an OpenAPI spec.\n\n wiki (bool):\n Build a hand-written wiki directory as its own MkDocs site.\n\n refresh (bool):\n Regenerate ``docs/mkdocs.{kind}.yml`` from templates even when\n it already exists. By default, existing configs are used as-is.\n\n module_is_source (bool):\n Treat the specified module directory as the project root.\n\n module (str | None):\n Python module import path to document.\n\n openapi_spec (Path | None):\n Path to the OpenAPI JSON specification used for API docs.\n\n project_name (str | None):\n Optional override for the project name.\n\n site_name (str | None):\n Display name for the lib and wiki MkDocs sites.\n\n docs_dir (Path):\n Shared documentation root used for generated sources.\n wiki_dir (Path):\n Directory containing hand-written wiki markdown files.\n\n nav_file (Path):\n Path to the navigation specification file.\n\n template (Path | None):\n Optional custom MkDocs configuration template.\n\n out_dir (Path):\n Output directory for generated MCP resources.\n\nRaises:\n click.UsageError:\n If required options are missing or conflicting." }, "serve": { "name": "serve", "kind": "function", "path": "docforge.cli.commands.serve", - "signature": "", + "signature": "", "docstring": "Serve generated documentation locally.\n\nDepending on the selected mode, this command starts either:\n\n- A MkDocs development server for browsing a site, or\n- An MCP server exposing structured documentation resources\n\nThe kind flags (`--lib`, `--api`, `--wiki`) select the generated\nper-kind config (`docs/mkdocs.{kind}.yml`); `--mkdocs` serves the config\npassed via `--mkdocs-yml`.\n\nArgs:\n mcp (bool):\n Serve documentation using the MCP server.\n\n mkdocs (bool):\n Serve the MkDocs development site from ``--mkdocs-yml``.\n\n lib (bool):\n Serve the lib MkDocs site.\n\n api (bool):\n Serve the API MkDocs site.\n\n wiki (bool):\n Serve the wiki MkDocs site.\n\n module (str | None):\n Python module import path to serve via MCP.\n\n mkdocs_yml (Path):\n Path to the MkDocs configuration file.\n\n out_dir (Path):\n Root directory containing MCP documentation resources.\n\nRaises:\n click.UsageError:\n If invalid or conflicting options are provided." }, "tree": { "name": "tree", "kind": "function", "path": "docforge.cli.commands.tree", - "signature": "", + "signature": "", "docstring": "Display the documentation object tree for a module.\n\nThis command introspects the specified module and prints a\nhierarchical representation of the discovered documentation\nobjects, including modules, classes, functions, and members.\n\nArgs:\n module (str):\n Python module import path to introspect.\n\n project_name (str | None):\n Optional name to display as the project root." }, "Group": {