3702 lines
146 KiB
HTML
3702 lines
146 KiB
HTML
|
||
<!doctype html>
|
||
<html lang="en" class="no-js">
|
||
<head>
|
||
|
||
<meta charset="utf-8">
|
||
<meta name="viewport" content="width=device-width,initial-scale=1">
|
||
|
||
|
||
|
||
|
||
|
||
<link rel="next" href="loaders/">
|
||
|
||
|
||
<link rel="icon" href="assets/images/favicon.png">
|
||
<meta name="generator" content="mkdocs-1.6.1, mkdocs-material-9.6.23">
|
||
|
||
|
||
|
||
<title>docforge</title>
|
||
|
||
|
||
|
||
<link rel="stylesheet" href="assets/stylesheets/main.84d31ad4.min.css">
|
||
|
||
|
||
<link rel="stylesheet" href="assets/stylesheets/palette.06af60db.min.css">
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
|
||
<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Inter:300,300i,400,400i,700,700i%7CJetBrains+Mono:400,400i,700,700i&display=fallback">
|
||
<style>:root{--md-text-font:"Inter";--md-code-font:"JetBrains Mono"}</style>
|
||
|
||
|
||
|
||
<link rel="stylesheet" href="assets/_mkdocstrings.css">
|
||
|
||
<link rel="stylesheet" href="https://unpkg.com/dracula-prism/dist/css/dracula-prism.css">
|
||
|
||
<script>__md_scope=new URL(".",location),__md_hash=e=>[...e].reduce(((e,_)=>(e<<5)-e+_.charCodeAt(0)),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
</head>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<body dir="ltr" data-md-color-scheme="slate" data-md-color-primary="deep-purple" data-md-color-accent="cyan">
|
||
|
||
|
||
<input class="md-toggle" data-md-toggle="drawer" type="checkbox" id="__drawer" autocomplete="off">
|
||
<input class="md-toggle" data-md-toggle="search" type="checkbox" id="__search" autocomplete="off">
|
||
<label class="md-overlay" for="__drawer"></label>
|
||
<div data-md-component="skip">
|
||
|
||
|
||
<a href="#docforge_1" class="md-skip">
|
||
Skip to content
|
||
</a>
|
||
|
||
</div>
|
||
<div data-md-component="announce">
|
||
|
||
</div>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<header class="md-header md-header--shadow" data-md-component="header">
|
||
<nav class="md-header__inner md-grid" aria-label="Header">
|
||
<a href="." title="docforge" class="md-header__button md-logo" aria-label="docforge" data-md-component="logo">
|
||
|
||
|
||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M4 4v18h16v2H4c-1.1 0-2-.9-2-2V4zm11 3h5.5L15 1.5zM8 0h8l6 6v12c0 1.11-.89 2-2 2H8a2 2 0 0 1-2-2V2c0-1.11.89-2 2-2m9 16v-2H8v2zm3-4v-2H8v2z"/></svg>
|
||
|
||
</a>
|
||
<label class="md-header__button md-icon" for="__drawer">
|
||
|
||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M3 6h18v2H3zm0 5h18v2H3zm0 5h18v2H3z"/></svg>
|
||
</label>
|
||
<div class="md-header__title" data-md-component="header-title">
|
||
<div class="md-header__ellipsis">
|
||
<div class="md-header__topic">
|
||
<span class="md-ellipsis">
|
||
docforge
|
||
</span>
|
||
</div>
|
||
<div class="md-header__topic" data-md-component="header-topic">
|
||
<span class="md-ellipsis">
|
||
|
||
Home
|
||
|
||
</span>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
|
||
|
||
<form class="md-header__option" data-md-component="palette">
|
||
|
||
|
||
|
||
|
||
<input class="md-option" data-md-color-media="" data-md-color-scheme="slate" data-md-color-primary="deep-purple" data-md-color-accent="cyan" aria-hidden="true" type="radio" name="__palette" id="__palette_0">
|
||
|
||
|
||
</form>
|
||
|
||
|
||
|
||
<script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent")}for(var[key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script>
|
||
|
||
|
||
|
||
|
||
|
||
<label class="md-header__button md-icon" for="__search">
|
||
|
||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.52 6.52 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5"/></svg>
|
||
</label>
|
||
<div class="md-search" data-md-component="search" role="dialog">
|
||
<label class="md-search__overlay" for="__search"></label>
|
||
<div class="md-search__inner" role="search">
|
||
<form class="md-search__form" name="search">
|
||
<input type="text" class="md-search__input" name="query" aria-label="Search" placeholder="Search" autocapitalize="off" autocorrect="off" autocomplete="off" spellcheck="false" data-md-component="search-query" required>
|
||
<label class="md-search__icon md-icon" for="__search">
|
||
|
||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.52 6.52 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5"/></svg>
|
||
|
||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11z"/></svg>
|
||
</label>
|
||
<nav class="md-search__options" aria-label="Search">
|
||
|
||
<a href="javascript:void(0)" class="md-search__icon md-icon" title="Share" aria-label="Share" data-clipboard data-clipboard-text="" data-md-component="search-share" tabindex="-1">
|
||
|
||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M18 16.08c-.76 0-1.44.3-1.96.77L8.91 12.7c.05-.23.09-.46.09-.7s-.04-.47-.09-.7l7.05-4.11c.54.5 1.25.81 2.04.81a3 3 0 0 0 3-3 3 3 0 0 0-3-3 3 3 0 0 0-3 3c0 .24.04.47.09.7L8.04 9.81C7.5 9.31 6.79 9 6 9a3 3 0 0 0-3 3 3 3 0 0 0 3 3c.79 0 1.5-.31 2.04-.81l7.12 4.15c-.05.21-.08.43-.08.66 0 1.61 1.31 2.91 2.92 2.91s2.92-1.3 2.92-2.91A2.92 2.92 0 0 0 18 16.08"/></svg>
|
||
</a>
|
||
|
||
<button type="reset" class="md-search__icon md-icon" title="Clear" aria-label="Clear" tabindex="-1">
|
||
|
||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M19 6.41 17.59 5 12 10.59 6.41 5 5 6.41 10.59 12 5 17.59 6.41 19 12 13.41 17.59 19 19 17.59 13.41 12z"/></svg>
|
||
</button>
|
||
</nav>
|
||
|
||
<div class="md-search__suggest" data-md-component="search-suggest"></div>
|
||
|
||
</form>
|
||
<div class="md-search__output">
|
||
<div class="md-search__scrollwrap" tabindex="0" data-md-scrollfix>
|
||
<div class="md-search-result" data-md-component="search-result">
|
||
<div class="md-search-result__meta">
|
||
Initializing search
|
||
</div>
|
||
<ol class="md-search-result__list" role="presentation"></ol>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
|
||
|
||
|
||
</nav>
|
||
|
||
</header>
|
||
|
||
<div class="md-container" data-md-component="container">
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<main class="md-main" data-md-component="main">
|
||
<div class="md-main__inner md-grid">
|
||
|
||
|
||
|
||
<div class="md-sidebar md-sidebar--primary" data-md-component="sidebar" data-md-type="navigation" >
|
||
<div class="md-sidebar__scrollwrap">
|
||
<div class="md-sidebar__inner">
|
||
|
||
|
||
|
||
|
||
<nav class="md-nav md-nav--primary" aria-label="Navigation" data-md-level="0">
|
||
<label class="md-nav__title" for="__drawer">
|
||
<a href="." title="docforge" class="md-nav__button md-logo" aria-label="docforge" data-md-component="logo">
|
||
|
||
|
||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M4 4v18h16v2H4c-1.1 0-2-.9-2-2V4zm11 3h5.5L15 1.5zM8 0h8l6 6v12c0 1.11-.89 2-2 2H8a2 2 0 0 1-2-2V2c0-1.11.89-2 2-2m9 16v-2H8v2zm3-4v-2H8v2z"/></svg>
|
||
|
||
</a>
|
||
docforge
|
||
</label>
|
||
|
||
<ul class="md-nav__list" data-md-scrollfix>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<li class="md-nav__item md-nav__item--active">
|
||
|
||
<input class="md-nav__toggle md-toggle" type="checkbox" id="__toc">
|
||
|
||
|
||
|
||
|
||
|
||
<label class="md-nav__link md-nav__link--active" for="__toc">
|
||
|
||
|
||
|
||
<span class="md-ellipsis">
|
||
Home
|
||
|
||
</span>
|
||
|
||
|
||
<span class="md-nav__icon md-icon"></span>
|
||
</label>
|
||
|
||
<a href="." class="md-nav__link md-nav__link--active">
|
||
|
||
|
||
|
||
<span class="md-ellipsis">
|
||
Home
|
||
|
||
</span>
|
||
|
||
|
||
</a>
|
||
|
||
|
||
|
||
<nav class="md-nav md-nav--secondary" aria-label="Table of contents">
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<label class="md-nav__title" for="__toc">
|
||
<span class="md-nav__icon md-icon"></span>
|
||
Table of contents
|
||
</label>
|
||
<ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#docforge" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
docforge
|
||
</span>
|
||
</a>
|
||
|
||
<nav class="md-nav" aria-label="docforge">
|
||
<ul class="md-nav__list">
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#docforge--summary" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Summary
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#docforge--installation" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Installation
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#docforge--cli-usage" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
CLI usage
|
||
</span>
|
||
</a>
|
||
|
||
<nav class="md-nav" aria-label="CLI usage">
|
||
<ul class="md-nav__list">
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#docforge--build-the-library-reference-from-a-python-package" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Build the library reference from a Python package:
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#docforge--build-the-api-reference-from-an-openapi-spec" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Build the API reference from an OpenAPI spec:
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#docforge--build-the-hand-written-wiki" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Build the hand-written wiki:
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#docforge--generate-mcp-json-documentation" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Generate MCP JSON documentation:
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#docforge--build-several-kinds-in-one-pass" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Build several kinds in one pass:
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#docforge--serve-a-site-locally" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Serve a site locally:
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#docforge--serve-mcp-locally" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Serve MCP locally:
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
</ul>
|
||
</nav>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#docforge--core-concepts" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Core concepts
|
||
</span>
|
||
</a>
|
||
|
||
<nav class="md-nav" aria-label="Core concepts">
|
||
<ul class="md-nav__list">
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#docforge--loader" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Loader
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#docforge--semantic-model" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Semantic model
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#docforge--renderer" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Renderer
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#docforge--symbol" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Symbol
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
</ul>
|
||
</nav>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#docforge--architecture" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Architecture
|
||
</span>
|
||
</a>
|
||
|
||
<nav class="md-nav" aria-label="Architecture">
|
||
<ul class="md-nav__list">
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#docforge--front-end" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Front-end:
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#docforge--middle-end" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Middle-end:
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#docforge--back-end" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Back-end:
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
</ul>
|
||
</nav>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#docforge--rendering-pipeline" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Rendering pipeline
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#docforge--google-styled-doc-forge-convention-gsdfc" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Google-Styled Doc-Forge Convention (GSDFC)
|
||
</span>
|
||
</a>
|
||
|
||
<nav class="md-nav" aria-label="Google-Styled Doc-Forge Convention (GSDFC)">
|
||
<ul class="md-nav__list">
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#docforge--general-rules" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
General rules
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
</ul>
|
||
</nav>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#docforge--notes-subsection-grouping" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Notes subsection grouping
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#docforge--example-formatting" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Example formatting
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#docforge--separator-rules" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Separator rules
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#docforge--package-docstrings" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Package docstrings
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#docforge--module-docstrings" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Module docstrings
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#docforge--class-docstrings" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Class docstrings
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#docforge--function-and-method-docstrings" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Function and method docstrings
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#docforge--property-docstrings" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Property docstrings
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#docforge--attribute-documentation" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Attribute documentation
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#docforge--type-parity-pyi-stubs-and-pytyped" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Type parity ( docforge Summary Renderer-agnostic Python documentation compiler that converts Python docstrings into structured documentation for both humans (MkDocs) and machines (MCP / AI agents). doc-forge statically analyzes source code, builds a semantic model of modules, classes, functions, and attributes, and renders that model into documentation outputs without executing user code. Installation Install using pip: 1pip install doc-forge CLI usage Each site kind (lib, api, wiki) is built independently into site/{kind}. Build the library reference from a Python package: 1doc-forge build --mkdocs --module my_package Build the API reference from an OpenAPI spec: 1doc-forge build --api --openapi-spec spec.json Build the hand-written wiki: 1doc-forge build --wiki --site-name my_package Generate MCP JSON documentation: 1doc-forge build --mcp --module my_package Build several kinds in one pass: 1doc-forge build --mcp --mkdocs --wiki --module my_package Each enabled kind gets its own MkDocs config (docs/mkdocs.{lib,api,wiki}.yml) and its own site under site/. Serve a site locally: 1 2 3 4 5doc-forge serve --wiki # preview from docs/mkdocs.wiki.yml doc-forge serve --lib doc-forge serve --api # or any config directly: doc-forge serve --mkdocs --mkdocs-yml docs/mkdocs.wiki.yml Serve MCP locally: 1doc-forge serve --mcp --module my_package Core concepts Loader Extracts symbols, signatures, and docstrings using static analysis. Semantic model Structured, renderer-agnostic representation of the API. Renderer Converts the semantic model into output formats such as MkDocs or MCP JSON. Symbol Any documentable object module class function method property attribute Architecture doc-forge follows a compiler architecture: Front-end: Static analysis of modules, classes, functions, type hints, and docstrings. Middle-end: Builds a semantic model describing symbols and relationships. Back-end: Renders documentation using interchangeable renderers. This architecture ensures deterministic documentation generation. Rendering pipeline Typical flow: 1 2 3 4 5 6 7 8 9Python package | Loader (static analysis) | Semantic model | Renderer | MkDocs site or MCP JSON Google-Styled Doc-Forge Convention (GSDFC) GSDFC defines how docstrings must be written so they render correctly in MkDocs and remain machine-parsable by doc-forge and AI tooling. Docstrings are the single source of truth. doc-forge compiles docstrings but does not generate documentation content. Documentation follows the Python import hierarchy. Every public symbol should have a complete and accurate docstring. General rules Use Markdown headings at package and module level. Use Google-style structured sections at class, function, and method level. Use type hints in signatures. Use parenthesized types in prose entries (name (Type):) that match the signature types. This keeps docstrings self-contained and machine-parseable. Write summaries in imperative form. Sections are separated by --- Notes subsection grouping Group related information using labeled subsections. Example: 1 2 3 4 5 6 7 8 9 10 11 12 13Notes: **Guarantees:** - deterministic behavior **Lifecycle:** - created during initialization - reused across executions **Thread safety:** - safe for concurrent reads Example formatting Use indentation for examples. Indent section contents using four spaces. Use code blocks for example code. Example Single example: 1 2 3 4 5 6Example: ```python foo = Foo("example") process(foo, multiplier=2) ``` Multiple examples: 1 2 3 4 5 6 7 8 9 10 11 12 13Example: Create foo: ```python foo = Foo("example") ``` Run engine: ```python engine = BarEngine([foo]) engine.run() ``` Avoid fenced code blocks inside argument descriptions and other prose lines. Inside Example: sections, fenced python code blocks are allowed and must be indented four spaces, matching the examples below. Separator rules Use horizontal separators only at docstring root level to separate sections: 1--- Allowed locations: package docstrings module docstrings major documentation sections Do not use separators inside code sections. Package docstrings Package docstrings act as the documentation home page. Recommended sections: 1 2 3 4 5 6 7 8 9# Summary # Installation # Quick start # CLI usage # Core concepts # Architecture # Rendering pipeline # Examples # Notes Example Package Doc String: 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30''' # Summary Foo-bar processing framework. Provides tools for defining Foo objects and executing Bar pipelines. --- # Installation ```bash pip install foo-bar ``` --- # Quick start ```python from foobar import Foo, BarEngine foo = Foo("example") engine = BarEngine([foo]) result = engine.run() ``` --- ''' Module docstrings Module docstrings describe a subsystem. Recommended sections: 1 2 3# Summary # Examples # Notes Example Module Doc String: 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23''' # Summary Foo execution subsystem. Provides utilities for executing Foo objects through Bar stages. --- Example: ```python from foobar.engine import BarEngine from foobar.foo import Foo foo = Foo("example") engine = BarEngine([foo]) engine.run() ``` --- ''' Class docstrings Class docstrings define object responsibility, lifecycle, and attributes. Recommended sections: 1 2 3 4Attributes: Notes: Example: Raises: Example Simple Foo: 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29class Foo: ''' Represents a unit of work. Attributes: name (str): Identifier of the foo instance. value (int): Numeric value associated with foo. Notes: Guarantees: - instances are immutable after creation Lifecycle: - create instance - pass to processing engine Example: Create and inspect a Foo: ```python foo = Foo("example", value=42) print(foo.name) ``` ''' Complex Bar: 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24class BarEngine: ''' Executes Foo objects through Bar stages. Attributes: foos (tuple[Foo, ...]): Foo instances managed by the engine. Notes: Guarantees: - deterministic execution order Example: Run engine: ```python foo1 = Foo("a") foo2 = Foo("b") engine = BarEngine([foo1, foo2]) engine.run() ``` ''' Function and method docstrings Function docstrings define API contracts. Recommended sections: 1 2 3 4 5 6Args: Returns: Raises: Yields: Notes: Example: Example Simple process method: 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34def process(foo: Foo, multiplier: int) -> int: ''' Process a Foo instance. Args: foo (Foo): Foo instance to process. multiplier (int): Value used to scale foo. Returns: int: Processed result. Raises: ValueError: If multiplier is negative. Notes: Guarantees: - foo is not modified Example: Process foo: ```python foo = Foo("example", value=10) result = process(foo, multiplier=2) print(result) ``` ''' Multiple Examples: 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32def combine(foo_a: Foo, foo_b: Foo) -> Foo: ''' Combine two Foo instances. Args: foo_a (Foo): First foo. foo_b (Foo): Second foo. Returns: Foo: Combined foo. Example: Basic usage: ```python foo1 = Foo("a") foo2 = Foo("b") combined = combine(foo1, foo2) ``` Pipeline usage: ```python engine = BarEngine([foo1, foo2]) engine.run() ``` ''' Property docstrings Properties must document return values. Example Property Doc String: 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18```python @property def foos(self) -> tuple[Foo, ...]: ''' Return contained Foo instances. Returns: tuple[Foo, ...]: Stored foo objects. Example: ```python container = FooContainer() foos = container.foos ``` ''' ``` Attribute documentation Document attributes in class docstrings using Attributes:. Example Attribute Doc String: 1 2 3 4 5 6 7 8 9 10 11 12```python ''' Represents a processing stage. Attributes: id (str): Unique identifier. enabled (bool): Whether the stage is active. ''' ``` Type parity (.pyi stubs and py.typed) Documented APIs ship matching type information: Each .py module has a synchronized .pyi stub in the same package. Packages expose a py.typed marker so type checkers (and consumers) use the authored signatures instead of Any. When signatures change, update the .py implementation and its .pyi stub together. Doc-forge documents the docstrings in .py; the .pyi stub is the machine-consumable signature surface. Parsing guarantees GSDFC ensures doc-forge can deterministically extract: symbol kind (module, class, function, property, attribute) symbol name parameters return values attributes examples structured Notes subsections This enables: reliable MkDocs rendering deterministic MCP export accurate AI semantic interpretation Notes doc-forge never executes analyzed modules. Documentation is generated entirely through static analysis. Classes GriffeLoader 1GriffeLoader() Load Python modules using Griffe and convert them into doc-forge models. This loader uses the Griffe introspection engine to analyze Python source code and transform the extracted information into Project, Module, and DocObject instances used by doc-forge. Attributes: Name Type Description _loader GriffeLoader Internal Griffe loader with dedicated module and line collections. Initialize the Griffe-backed loader. Creates an internal Griffe loader instance with dedicated collections for modules and source lines. Functions load_module 1load_module(path: str) -> Module Load and convert a single Python module. The module is introspected using Griffe and then transformed into a doc-forge Module model. Parameters: Name Type Description Default path str Dotted import path of the module. required Returns: Name Type Description Module Module A populated Module instance. Raises: Type Description ImportError If the module cannot be loaded by Griffe. KeyError If the loaded module is missing from the module collection. Example Load a single module: 1 2 3 4```python loader = GriffeLoader() module = loader.load_module("mypackage.submodule") ``` load_project 1 2 3 4 5load_project( module_paths: list[str], project_name: str | None = None, skip_import_errors: bool | None = None, ) -> Project Load multiple modules and assemble them into a Project model. Each module path is introspected and converted into a Module instance. All modules are then aggregated into a single Project object. Parameters: Name Type Description Default module_paths list[str] List of dotted module import paths to load. required project_name str | None Optional override for the project name. Defaults to the top-level name of the first module. None skip_import_errors bool | None If True, modules that fail to load will be skipped instead of raising an error. None Returns: Name Type Description Project Project A populated Project instance containing the loaded modules. Raises: Type Description ValueError If no module paths are provided. ImportError If a module fails to load and skip_import_errors is False. MCPRenderer Renderer that generates MCP-compatible documentation resources. This renderer converts doc-forge project models into structured JSON resources suitable for consumption by systems implementing the Model Context Protocol (MCP). Functions generate_sources 1generate_sources(project: Project, out_dir: Path) -> None Generate MCP documentation resources for a project. The renderer serializes each module into a JSON resource and produces supporting metadata files such as nav.json and index.json. Parameters: Name Type Description Default project Project Documentation project model to render. required out_dir Path Directory where MCP resources will be written. required MkDocsRenderer Renderer that produces Markdown documentation for MkDocs. Generated pages use mkdocstrings directives to reference Python modules, allowing MkDocs to render API documentation dynamically. Functions generate_readme 1 2 3 4 5 6generate_readme( project: Project, docs_dir: Path, module_is_source: bool | None = None, readme_dir: Path | None = None, ) -> None Generate a README.md file from the root module docstring. Notes If module_is_source is True, README.md is written to the project root directory. If False, README generation is currently not implemented. Parameters: Name Type Description Default project Project Project model containing documentation metadata. required docs_dir Path Directory containing generated documentation sources. required module_is_source bool | None Whether the module is treated as the project source root. None readme_dir Path | None Directory where the generated README.md should be written. Defaults to the parent of docs_dir. None generate_sources 1 2 3 4 5generate_sources( project: Project, out_dir: Path, module_is_source: bool | None = None, ) -> None Generate Markdown documentation files for a project. This method renders a documentation structure from the provided project model and writes the resulting Markdown files to the specified output directory. Parameters: Name Type Description Default project Project Project model containing modules to document. required out_dir Path Directory where generated Markdown files will be written. required module_is_source bool | None If True, treat the specified module as the documentation root rather than nesting it inside a folder. None Functions discover_module_paths 1 2 3discover_module_paths( module_name: str, project_root: Path | None = None ) -> list[str] Discover Python modules within a package directory. The function scans the filesystem for .py files inside the specified package and converts them into dotted module import paths. Discovery rules: Directories containing __init__.py are treated as packages. Each .py file is treated as a module. Results are returned as dotted import paths. Parameters: Name Type Description Default module_name str Top-level package name to discover modules from. required project_root Path | None Root directory used to resolve module paths. If not provided, the current working directory is used. None Returns: Type Description list[str] list[str]: A sorted list of unique dotted module import paths. Raises: Type Description FileNotFoundError If the specified package directory does not exist. stubs and wzxhzdk:1)
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#docforge--parsing-guarantees" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Parsing guarantees
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#docforge-classes" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Classes
|
||
</span>
|
||
</a>
|
||
|
||
<nav class="md-nav" aria-label="Classes">
|
||
<ul class="md-nav__list">
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#docforge.GriffeLoader" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
GriffeLoader
|
||
</span>
|
||
</a>
|
||
|
||
<nav class="md-nav" aria-label="GriffeLoader">
|
||
<ul class="md-nav__list">
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#docforge.GriffeLoader-functions" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Functions
|
||
</span>
|
||
</a>
|
||
|
||
<nav class="md-nav" aria-label="Functions">
|
||
<ul class="md-nav__list">
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#docforge.GriffeLoader.load_module" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
load_module
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#docforge.GriffeLoader.load_project" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
load_project
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
</ul>
|
||
</nav>
|
||
|
||
</li>
|
||
|
||
</ul>
|
||
</nav>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#docforge.MCPRenderer" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
MCPRenderer
|
||
</span>
|
||
</a>
|
||
|
||
<nav class="md-nav" aria-label="MCPRenderer">
|
||
<ul class="md-nav__list">
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#docforge.MCPRenderer-functions" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Functions
|
||
</span>
|
||
</a>
|
||
|
||
<nav class="md-nav" aria-label="Functions">
|
||
<ul class="md-nav__list">
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#docforge.MCPRenderer.generate_sources" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
generate_sources
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
</ul>
|
||
</nav>
|
||
|
||
</li>
|
||
|
||
</ul>
|
||
</nav>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#docforge.MkDocsRenderer" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
MkDocsRenderer
|
||
</span>
|
||
</a>
|
||
|
||
<nav class="md-nav" aria-label="MkDocsRenderer">
|
||
<ul class="md-nav__list">
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#docforge.MkDocsRenderer-functions" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Functions
|
||
</span>
|
||
</a>
|
||
|
||
<nav class="md-nav" aria-label="Functions">
|
||
<ul class="md-nav__list">
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#docforge.MkDocsRenderer.generate_readme" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
generate_readme
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#docforge.MkDocsRenderer.generate_sources" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
generate_sources
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
</ul>
|
||
</nav>
|
||
|
||
</li>
|
||
|
||
</ul>
|
||
</nav>
|
||
|
||
</li>
|
||
|
||
</ul>
|
||
</nav>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#docforge-functions" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Functions
|
||
</span>
|
||
</a>
|
||
|
||
<nav class="md-nav" aria-label="Functions">
|
||
<ul class="md-nav__list">
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#docforge.discover_module_paths" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
discover_module_paths
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
</ul>
|
||
</nav>
|
||
|
||
</li>
|
||
|
||
</ul>
|
||
</nav>
|
||
|
||
</li>
|
||
|
||
</ul>
|
||
|
||
</nav>
|
||
|
||
</li>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<li class="md-nav__item md-nav__item--section md-nav__item--nested">
|
||
|
||
|
||
|
||
|
||
|
||
<input class="md-nav__toggle md-toggle md-toggle--indeterminate" type="checkbox" id="__nav_2" >
|
||
|
||
|
||
<div class="md-nav__link md-nav__container">
|
||
<a href="loaders/" class="md-nav__link ">
|
||
|
||
|
||
|
||
<span class="md-ellipsis">
|
||
Loaders
|
||
|
||
</span>
|
||
|
||
|
||
</a>
|
||
|
||
|
||
<label class="md-nav__link " for="__nav_2" id="__nav_2_label" tabindex="">
|
||
<span class="md-nav__icon md-icon"></span>
|
||
</label>
|
||
|
||
</div>
|
||
|
||
<nav class="md-nav" data-md-level="1" aria-labelledby="__nav_2_label" aria-expanded="false">
|
||
<label class="md-nav__title" for="__nav_2">
|
||
<span class="md-nav__icon md-icon"></span>
|
||
Loaders
|
||
</label>
|
||
<ul class="md-nav__list" data-md-scrollfix>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<li class="md-nav__item">
|
||
<a href="loaders/griffe_loader/" class="md-nav__link">
|
||
|
||
|
||
|
||
<span class="md-ellipsis">
|
||
Griffe Loader
|
||
|
||
</span>
|
||
|
||
|
||
</a>
|
||
</li>
|
||
|
||
|
||
|
||
|
||
</ul>
|
||
</nav>
|
||
|
||
</li>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<li class="md-nav__item md-nav__item--section md-nav__item--nested">
|
||
|
||
|
||
|
||
|
||
|
||
<input class="md-nav__toggle md-toggle md-toggle--indeterminate" type="checkbox" id="__nav_3" >
|
||
|
||
|
||
<div class="md-nav__link md-nav__container">
|
||
<a href="models/" class="md-nav__link ">
|
||
|
||
|
||
|
||
<span class="md-ellipsis">
|
||
Models
|
||
|
||
</span>
|
||
|
||
|
||
</a>
|
||
|
||
|
||
<label class="md-nav__link " for="__nav_3" id="__nav_3_label" tabindex="">
|
||
<span class="md-nav__icon md-icon"></span>
|
||
</label>
|
||
|
||
</div>
|
||
|
||
<nav class="md-nav" data-md-level="1" aria-labelledby="__nav_3_label" aria-expanded="false">
|
||
<label class="md-nav__title" for="__nav_3">
|
||
<span class="md-nav__icon md-icon"></span>
|
||
Models
|
||
</label>
|
||
<ul class="md-nav__list" data-md-scrollfix>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<li class="md-nav__item">
|
||
<a href="models/module/" class="md-nav__link">
|
||
|
||
|
||
|
||
<span class="md-ellipsis">
|
||
Module
|
||
|
||
</span>
|
||
|
||
|
||
</a>
|
||
</li>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<li class="md-nav__item">
|
||
<a href="models/object/" class="md-nav__link">
|
||
|
||
|
||
|
||
<span class="md-ellipsis">
|
||
Object
|
||
|
||
</span>
|
||
|
||
|
||
</a>
|
||
</li>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<li class="md-nav__item">
|
||
<a href="models/project/" class="md-nav__link">
|
||
|
||
|
||
|
||
<span class="md-ellipsis">
|
||
Project
|
||
|
||
</span>
|
||
|
||
|
||
</a>
|
||
</li>
|
||
|
||
|
||
|
||
|
||
</ul>
|
||
</nav>
|
||
|
||
</li>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<li class="md-nav__item md-nav__item--section md-nav__item--nested">
|
||
|
||
|
||
|
||
|
||
|
||
<input class="md-nav__toggle md-toggle md-toggle--indeterminate" type="checkbox" id="__nav_4" >
|
||
|
||
|
||
<div class="md-nav__link md-nav__container">
|
||
<a href="nav/" class="md-nav__link ">
|
||
|
||
|
||
|
||
<span class="md-ellipsis">
|
||
Navigation
|
||
|
||
</span>
|
||
|
||
|
||
</a>
|
||
|
||
|
||
<label class="md-nav__link " for="__nav_4" id="__nav_4_label" tabindex="">
|
||
<span class="md-nav__icon md-icon"></span>
|
||
</label>
|
||
|
||
</div>
|
||
|
||
<nav class="md-nav" data-md-level="1" aria-labelledby="__nav_4_label" aria-expanded="false">
|
||
<label class="md-nav__title" for="__nav_4">
|
||
<span class="md-nav__icon md-icon"></span>
|
||
Navigation
|
||
</label>
|
||
<ul class="md-nav__list" data-md-scrollfix>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<li class="md-nav__item">
|
||
<a href="nav/spec/" class="md-nav__link">
|
||
|
||
|
||
|
||
<span class="md-ellipsis">
|
||
Spec
|
||
|
||
</span>
|
||
|
||
|
||
</a>
|
||
</li>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<li class="md-nav__item">
|
||
<a href="nav/resolver/" class="md-nav__link">
|
||
|
||
|
||
|
||
<span class="md-ellipsis">
|
||
Resolver
|
||
|
||
</span>
|
||
|
||
|
||
</a>
|
||
</li>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<li class="md-nav__item">
|
||
<a href="nav/mkdocs/" class="md-nav__link">
|
||
|
||
|
||
|
||
<span class="md-ellipsis">
|
||
Mkdocs
|
||
|
||
</span>
|
||
|
||
|
||
</a>
|
||
</li>
|
||
|
||
|
||
|
||
|
||
</ul>
|
||
</nav>
|
||
|
||
</li>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<li class="md-nav__item md-nav__item--section md-nav__item--nested">
|
||
|
||
|
||
|
||
|
||
|
||
<input class="md-nav__toggle md-toggle md-toggle--indeterminate" type="checkbox" id="__nav_5" >
|
||
|
||
|
||
<div class="md-nav__link md-nav__container">
|
||
<a href="renderers/" class="md-nav__link ">
|
||
|
||
|
||
|
||
<span class="md-ellipsis">
|
||
Renderers
|
||
|
||
</span>
|
||
|
||
|
||
</a>
|
||
|
||
|
||
<label class="md-nav__link " for="__nav_5" id="__nav_5_label" tabindex="">
|
||
<span class="md-nav__icon md-icon"></span>
|
||
</label>
|
||
|
||
</div>
|
||
|
||
<nav class="md-nav" data-md-level="1" aria-labelledby="__nav_5_label" aria-expanded="false">
|
||
<label class="md-nav__title" for="__nav_5">
|
||
<span class="md-nav__icon md-icon"></span>
|
||
Renderers
|
||
</label>
|
||
<ul class="md-nav__list" data-md-scrollfix>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<li class="md-nav__item">
|
||
<a href="renderers/base/" class="md-nav__link">
|
||
|
||
|
||
|
||
<span class="md-ellipsis">
|
||
Base
|
||
|
||
</span>
|
||
|
||
|
||
</a>
|
||
</li>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<li class="md-nav__item">
|
||
<a href="renderers/mkdocs_renderer/" class="md-nav__link">
|
||
|
||
|
||
|
||
<span class="md-ellipsis">
|
||
Mkdocs Renderer
|
||
|
||
</span>
|
||
|
||
|
||
</a>
|
||
</li>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<li class="md-nav__item">
|
||
<a href="renderers/mcp_renderer/" class="md-nav__link">
|
||
|
||
|
||
|
||
<span class="md-ellipsis">
|
||
Mcp Renderer
|
||
|
||
</span>
|
||
|
||
|
||
</a>
|
||
</li>
|
||
|
||
|
||
|
||
|
||
</ul>
|
||
</nav>
|
||
|
||
</li>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<li class="md-nav__item md-nav__item--section md-nav__item--nested">
|
||
|
||
|
||
|
||
|
||
|
||
<input class="md-nav__toggle md-toggle md-toggle--indeterminate" type="checkbox" id="__nav_6" >
|
||
|
||
|
||
<div class="md-nav__link md-nav__container">
|
||
<a href="cli/" class="md-nav__link ">
|
||
|
||
|
||
|
||
<span class="md-ellipsis">
|
||
CLI
|
||
|
||
</span>
|
||
|
||
|
||
</a>
|
||
|
||
|
||
<label class="md-nav__link " for="__nav_6" id="__nav_6_label" tabindex="">
|
||
<span class="md-nav__icon md-icon"></span>
|
||
</label>
|
||
|
||
</div>
|
||
|
||
<nav class="md-nav" data-md-level="1" aria-labelledby="__nav_6_label" aria-expanded="false">
|
||
<label class="md-nav__title" for="__nav_6">
|
||
<span class="md-nav__icon md-icon"></span>
|
||
CLI
|
||
</label>
|
||
<ul class="md-nav__list" data-md-scrollfix>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<li class="md-nav__item">
|
||
<a href="cli/main/" class="md-nav__link">
|
||
|
||
|
||
|
||
<span class="md-ellipsis">
|
||
Main
|
||
|
||
</span>
|
||
|
||
|
||
</a>
|
||
</li>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<li class="md-nav__item">
|
||
<a href="cli/commands/" class="md-nav__link">
|
||
|
||
|
||
|
||
<span class="md-ellipsis">
|
||
Commands
|
||
|
||
</span>
|
||
|
||
|
||
</a>
|
||
</li>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<li class="md-nav__item">
|
||
<a href="cli/api_utils/" class="md-nav__link">
|
||
|
||
|
||
|
||
<span class="md-ellipsis">
|
||
Api Utils
|
||
|
||
</span>
|
||
|
||
|
||
</a>
|
||
</li>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<li class="md-nav__item">
|
||
<a href="cli/mcp_utils/" class="md-nav__link">
|
||
|
||
|
||
|
||
<span class="md-ellipsis">
|
||
Mcp Utils
|
||
|
||
</span>
|
||
|
||
|
||
</a>
|
||
</li>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<li class="md-nav__item">
|
||
<a href="cli/mkdocs_utils/" class="md-nav__link">
|
||
|
||
|
||
|
||
<span class="md-ellipsis">
|
||
Mkdocs Utils
|
||
|
||
</span>
|
||
|
||
|
||
</a>
|
||
</li>
|
||
|
||
|
||
|
||
|
||
</ul>
|
||
</nav>
|
||
|
||
</li>
|
||
|
||
|
||
|
||
</ul>
|
||
</nav>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
|
||
|
||
|
||
<div class="md-sidebar md-sidebar--secondary" data-md-component="sidebar" data-md-type="toc" >
|
||
<div class="md-sidebar__scrollwrap">
|
||
<div class="md-sidebar__inner">
|
||
|
||
|
||
<nav class="md-nav md-nav--secondary" aria-label="Table of contents">
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<label class="md-nav__title" for="__toc">
|
||
<span class="md-nav__icon md-icon"></span>
|
||
Table of contents
|
||
</label>
|
||
<ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#docforge" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
docforge
|
||
</span>
|
||
</a>
|
||
|
||
<nav class="md-nav" aria-label="docforge">
|
||
<ul class="md-nav__list">
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#docforge--summary" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Summary
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#docforge--installation" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Installation
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#docforge--cli-usage" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
CLI usage
|
||
</span>
|
||
</a>
|
||
|
||
<nav class="md-nav" aria-label="CLI usage">
|
||
<ul class="md-nav__list">
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#docforge--build-the-library-reference-from-a-python-package" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Build the library reference from a Python package:
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#docforge--build-the-api-reference-from-an-openapi-spec" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Build the API reference from an OpenAPI spec:
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#docforge--build-the-hand-written-wiki" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Build the hand-written wiki:
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#docforge--generate-mcp-json-documentation" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Generate MCP JSON documentation:
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#docforge--build-several-kinds-in-one-pass" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Build several kinds in one pass:
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#docforge--serve-a-site-locally" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Serve a site locally:
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#docforge--serve-mcp-locally" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Serve MCP locally:
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
</ul>
|
||
</nav>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#docforge--core-concepts" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Core concepts
|
||
</span>
|
||
</a>
|
||
|
||
<nav class="md-nav" aria-label="Core concepts">
|
||
<ul class="md-nav__list">
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#docforge--loader" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Loader
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#docforge--semantic-model" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Semantic model
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#docforge--renderer" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Renderer
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#docforge--symbol" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Symbol
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
</ul>
|
||
</nav>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#docforge--architecture" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Architecture
|
||
</span>
|
||
</a>
|
||
|
||
<nav class="md-nav" aria-label="Architecture">
|
||
<ul class="md-nav__list">
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#docforge--front-end" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Front-end:
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#docforge--middle-end" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Middle-end:
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#docforge--back-end" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Back-end:
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
</ul>
|
||
</nav>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#docforge--rendering-pipeline" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Rendering pipeline
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#docforge--google-styled-doc-forge-convention-gsdfc" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Google-Styled Doc-Forge Convention (GSDFC)
|
||
</span>
|
||
</a>
|
||
|
||
<nav class="md-nav" aria-label="Google-Styled Doc-Forge Convention (GSDFC)">
|
||
<ul class="md-nav__list">
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#docforge--general-rules" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
General rules
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
</ul>
|
||
</nav>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#docforge--notes-subsection-grouping" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Notes subsection grouping
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#docforge--example-formatting" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Example formatting
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#docforge--separator-rules" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Separator rules
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#docforge--package-docstrings" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Package docstrings
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#docforge--module-docstrings" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Module docstrings
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#docforge--class-docstrings" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Class docstrings
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#docforge--function-and-method-docstrings" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Function and method docstrings
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#docforge--property-docstrings" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Property docstrings
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#docforge--attribute-documentation" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Attribute documentation
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#docforge--type-parity-pyi-stubs-and-pytyped" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Type parity ( docforge Summary Renderer-agnostic Python documentation compiler that converts Python docstrings into structured documentation for both humans (MkDocs) and machines (MCP / AI agents). doc-forge statically analyzes source code, builds a semantic model of modules, classes, functions, and attributes, and renders that model into documentation outputs without executing user code. Installation Install using pip: 1pip install doc-forge CLI usage Each site kind (lib, api, wiki) is built independently into site/{kind}. Build the library reference from a Python package: 1doc-forge build --mkdocs --module my_package Build the API reference from an OpenAPI spec: 1doc-forge build --api --openapi-spec spec.json Build the hand-written wiki: 1doc-forge build --wiki --site-name my_package Generate MCP JSON documentation: 1doc-forge build --mcp --module my_package Build several kinds in one pass: 1doc-forge build --mcp --mkdocs --wiki --module my_package Each enabled kind gets its own MkDocs config (docs/mkdocs.{lib,api,wiki}.yml) and its own site under site/. Serve a site locally: 1 2 3 4 5doc-forge serve --wiki # preview from docs/mkdocs.wiki.yml doc-forge serve --lib doc-forge serve --api # or any config directly: doc-forge serve --mkdocs --mkdocs-yml docs/mkdocs.wiki.yml Serve MCP locally: 1doc-forge serve --mcp --module my_package Core concepts Loader Extracts symbols, signatures, and docstrings using static analysis. Semantic model Structured, renderer-agnostic representation of the API. Renderer Converts the semantic model into output formats such as MkDocs or MCP JSON. Symbol Any documentable object module class function method property attribute Architecture doc-forge follows a compiler architecture: Front-end: Static analysis of modules, classes, functions, type hints, and docstrings. Middle-end: Builds a semantic model describing symbols and relationships. Back-end: Renders documentation using interchangeable renderers. This architecture ensures deterministic documentation generation. Rendering pipeline Typical flow: 1 2 3 4 5 6 7 8 9Python package | Loader (static analysis) | Semantic model | Renderer | MkDocs site or MCP JSON Google-Styled Doc-Forge Convention (GSDFC) GSDFC defines how docstrings must be written so they render correctly in MkDocs and remain machine-parsable by doc-forge and AI tooling. Docstrings are the single source of truth. doc-forge compiles docstrings but does not generate documentation content. Documentation follows the Python import hierarchy. Every public symbol should have a complete and accurate docstring. General rules Use Markdown headings at package and module level. Use Google-style structured sections at class, function, and method level. Use type hints in signatures. Use parenthesized types in prose entries (name (Type):) that match the signature types. This keeps docstrings self-contained and machine-parseable. Write summaries in imperative form. Sections are separated by --- Notes subsection grouping Group related information using labeled subsections. Example: 1 2 3 4 5 6 7 8 9 10 11 12 13Notes: **Guarantees:** - deterministic behavior **Lifecycle:** - created during initialization - reused across executions **Thread safety:** - safe for concurrent reads Example formatting Use indentation for examples. Indent section contents using four spaces. Use code blocks for example code. Example Single example: 1 2 3 4 5 6Example: ```python foo = Foo("example") process(foo, multiplier=2) ``` Multiple examples: 1 2 3 4 5 6 7 8 9 10 11 12 13Example: Create foo: ```python foo = Foo("example") ``` Run engine: ```python engine = BarEngine([foo]) engine.run() ``` Avoid fenced code blocks inside argument descriptions and other prose lines. Inside Example: sections, fenced python code blocks are allowed and must be indented four spaces, matching the examples below. Separator rules Use horizontal separators only at docstring root level to separate sections: 1--- Allowed locations: package docstrings module docstrings major documentation sections Do not use separators inside code sections. Package docstrings Package docstrings act as the documentation home page. Recommended sections: 1 2 3 4 5 6 7 8 9# Summary # Installation # Quick start # CLI usage # Core concepts # Architecture # Rendering pipeline # Examples # Notes Example Package Doc String: 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30''' # Summary Foo-bar processing framework. Provides tools for defining Foo objects and executing Bar pipelines. --- # Installation ```bash pip install foo-bar ``` --- # Quick start ```python from foobar import Foo, BarEngine foo = Foo("example") engine = BarEngine([foo]) result = engine.run() ``` --- ''' Module docstrings Module docstrings describe a subsystem. Recommended sections: 1 2 3# Summary # Examples # Notes Example Module Doc String: 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23''' # Summary Foo execution subsystem. Provides utilities for executing Foo objects through Bar stages. --- Example: ```python from foobar.engine import BarEngine from foobar.foo import Foo foo = Foo("example") engine = BarEngine([foo]) engine.run() ``` --- ''' Class docstrings Class docstrings define object responsibility, lifecycle, and attributes. Recommended sections: 1 2 3 4Attributes: Notes: Example: Raises: Example Simple Foo: 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29class Foo: ''' Represents a unit of work. Attributes: name (str): Identifier of the foo instance. value (int): Numeric value associated with foo. Notes: Guarantees: - instances are immutable after creation Lifecycle: - create instance - pass to processing engine Example: Create and inspect a Foo: ```python foo = Foo("example", value=42) print(foo.name) ``` ''' Complex Bar: 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24class BarEngine: ''' Executes Foo objects through Bar stages. Attributes: foos (tuple[Foo, ...]): Foo instances managed by the engine. Notes: Guarantees: - deterministic execution order Example: Run engine: ```python foo1 = Foo("a") foo2 = Foo("b") engine = BarEngine([foo1, foo2]) engine.run() ``` ''' Function and method docstrings Function docstrings define API contracts. Recommended sections: 1 2 3 4 5 6Args: Returns: Raises: Yields: Notes: Example: Example Simple process method: 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34def process(foo: Foo, multiplier: int) -> int: ''' Process a Foo instance. Args: foo (Foo): Foo instance to process. multiplier (int): Value used to scale foo. Returns: int: Processed result. Raises: ValueError: If multiplier is negative. Notes: Guarantees: - foo is not modified Example: Process foo: ```python foo = Foo("example", value=10) result = process(foo, multiplier=2) print(result) ``` ''' Multiple Examples: 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32def combine(foo_a: Foo, foo_b: Foo) -> Foo: ''' Combine two Foo instances. Args: foo_a (Foo): First foo. foo_b (Foo): Second foo. Returns: Foo: Combined foo. Example: Basic usage: ```python foo1 = Foo("a") foo2 = Foo("b") combined = combine(foo1, foo2) ``` Pipeline usage: ```python engine = BarEngine([foo1, foo2]) engine.run() ``` ''' Property docstrings Properties must document return values. Example Property Doc String: 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18```python @property def foos(self) -> tuple[Foo, ...]: ''' Return contained Foo instances. Returns: tuple[Foo, ...]: Stored foo objects. Example: ```python container = FooContainer() foos = container.foos ``` ''' ``` Attribute documentation Document attributes in class docstrings using Attributes:. Example Attribute Doc String: 1 2 3 4 5 6 7 8 9 10 11 12```python ''' Represents a processing stage. Attributes: id (str): Unique identifier. enabled (bool): Whether the stage is active. ''' ``` Type parity (.pyi stubs and py.typed) Documented APIs ship matching type information: Each .py module has a synchronized .pyi stub in the same package. Packages expose a py.typed marker so type checkers (and consumers) use the authored signatures instead of Any. When signatures change, update the .py implementation and its .pyi stub together. Doc-forge documents the docstrings in .py; the .pyi stub is the machine-consumable signature surface. Parsing guarantees GSDFC ensures doc-forge can deterministically extract: symbol kind (module, class, function, property, attribute) symbol name parameters return values attributes examples structured Notes subsections This enables: reliable MkDocs rendering deterministic MCP export accurate AI semantic interpretation Notes doc-forge never executes analyzed modules. Documentation is generated entirely through static analysis. Classes GriffeLoader 1GriffeLoader() Load Python modules using Griffe and convert them into doc-forge models. This loader uses the Griffe introspection engine to analyze Python source code and transform the extracted information into Project, Module, and DocObject instances used by doc-forge. Attributes: Name Type Description _loader GriffeLoader Internal Griffe loader with dedicated module and line collections. Initialize the Griffe-backed loader. Creates an internal Griffe loader instance with dedicated collections for modules and source lines. Functions load_module 1load_module(path: str) -> Module Load and convert a single Python module. The module is introspected using Griffe and then transformed into a doc-forge Module model. Parameters: Name Type Description Default path str Dotted import path of the module. required Returns: Name Type Description Module Module A populated Module instance. Raises: Type Description ImportError If the module cannot be loaded by Griffe. KeyError If the loaded module is missing from the module collection. Example Load a single module: 1 2 3 4```python loader = GriffeLoader() module = loader.load_module("mypackage.submodule") ``` load_project 1 2 3 4 5load_project( module_paths: list[str], project_name: str | None = None, skip_import_errors: bool | None = None, ) -> Project Load multiple modules and assemble them into a Project model. Each module path is introspected and converted into a Module instance. All modules are then aggregated into a single Project object. Parameters: Name Type Description Default module_paths list[str] List of dotted module import paths to load. required project_name str | None Optional override for the project name. Defaults to the top-level name of the first module. None skip_import_errors bool | None If True, modules that fail to load will be skipped instead of raising an error. None Returns: Name Type Description Project Project A populated Project instance containing the loaded modules. Raises: Type Description ValueError If no module paths are provided. ImportError If a module fails to load and skip_import_errors is False. MCPRenderer Renderer that generates MCP-compatible documentation resources. This renderer converts doc-forge project models into structured JSON resources suitable for consumption by systems implementing the Model Context Protocol (MCP). Functions generate_sources 1generate_sources(project: Project, out_dir: Path) -> None Generate MCP documentation resources for a project. The renderer serializes each module into a JSON resource and produces supporting metadata files such as nav.json and index.json. Parameters: Name Type Description Default project Project Documentation project model to render. required out_dir Path Directory where MCP resources will be written. required MkDocsRenderer Renderer that produces Markdown documentation for MkDocs. Generated pages use mkdocstrings directives to reference Python modules, allowing MkDocs to render API documentation dynamically. Functions generate_readme 1 2 3 4 5 6generate_readme( project: Project, docs_dir: Path, module_is_source: bool | None = None, readme_dir: Path | None = None, ) -> None Generate a README.md file from the root module docstring. Notes If module_is_source is True, README.md is written to the project root directory. If False, README generation is currently not implemented. Parameters: Name Type Description Default project Project Project model containing documentation metadata. required docs_dir Path Directory containing generated documentation sources. required module_is_source bool | None Whether the module is treated as the project source root. None readme_dir Path | None Directory where the generated README.md should be written. Defaults to the parent of docs_dir. None generate_sources 1 2 3 4 5generate_sources( project: Project, out_dir: Path, module_is_source: bool | None = None, ) -> None Generate Markdown documentation files for a project. This method renders a documentation structure from the provided project model and writes the resulting Markdown files to the specified output directory. Parameters: Name Type Description Default project Project Project model containing modules to document. required out_dir Path Directory where generated Markdown files will be written. required module_is_source bool | None If True, treat the specified module as the documentation root rather than nesting it inside a folder. None Functions discover_module_paths 1 2 3discover_module_paths( module_name: str, project_root: Path | None = None ) -> list[str] Discover Python modules within a package directory. The function scans the filesystem for .py files inside the specified package and converts them into dotted module import paths. Discovery rules: Directories containing __init__.py are treated as packages. Each .py file is treated as a module. Results are returned as dotted import paths. Parameters: Name Type Description Default module_name str Top-level package name to discover modules from. required project_root Path | None Root directory used to resolve module paths. If not provided, the current working directory is used. None Returns: Type Description list[str] list[str]: A sorted list of unique dotted module import paths. Raises: Type Description FileNotFoundError If the specified package directory does not exist. stubs and wzxhzdk:1)
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#docforge--parsing-guarantees" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Parsing guarantees
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#docforge-classes" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Classes
|
||
</span>
|
||
</a>
|
||
|
||
<nav class="md-nav" aria-label="Classes">
|
||
<ul class="md-nav__list">
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#docforge.GriffeLoader" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
GriffeLoader
|
||
</span>
|
||
</a>
|
||
|
||
<nav class="md-nav" aria-label="GriffeLoader">
|
||
<ul class="md-nav__list">
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#docforge.GriffeLoader-functions" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Functions
|
||
</span>
|
||
</a>
|
||
|
||
<nav class="md-nav" aria-label="Functions">
|
||
<ul class="md-nav__list">
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#docforge.GriffeLoader.load_module" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
load_module
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#docforge.GriffeLoader.load_project" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
load_project
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
</ul>
|
||
</nav>
|
||
|
||
</li>
|
||
|
||
</ul>
|
||
</nav>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#docforge.MCPRenderer" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
MCPRenderer
|
||
</span>
|
||
</a>
|
||
|
||
<nav class="md-nav" aria-label="MCPRenderer">
|
||
<ul class="md-nav__list">
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#docforge.MCPRenderer-functions" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Functions
|
||
</span>
|
||
</a>
|
||
|
||
<nav class="md-nav" aria-label="Functions">
|
||
<ul class="md-nav__list">
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#docforge.MCPRenderer.generate_sources" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
generate_sources
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
</ul>
|
||
</nav>
|
||
|
||
</li>
|
||
|
||
</ul>
|
||
</nav>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#docforge.MkDocsRenderer" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
MkDocsRenderer
|
||
</span>
|
||
</a>
|
||
|
||
<nav class="md-nav" aria-label="MkDocsRenderer">
|
||
<ul class="md-nav__list">
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#docforge.MkDocsRenderer-functions" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Functions
|
||
</span>
|
||
</a>
|
||
|
||
<nav class="md-nav" aria-label="Functions">
|
||
<ul class="md-nav__list">
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#docforge.MkDocsRenderer.generate_readme" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
generate_readme
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#docforge.MkDocsRenderer.generate_sources" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
generate_sources
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
</ul>
|
||
</nav>
|
||
|
||
</li>
|
||
|
||
</ul>
|
||
</nav>
|
||
|
||
</li>
|
||
|
||
</ul>
|
||
</nav>
|
||
|
||
</li>
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#docforge-functions" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
Functions
|
||
</span>
|
||
</a>
|
||
|
||
<nav class="md-nav" aria-label="Functions">
|
||
<ul class="md-nav__list">
|
||
|
||
<li class="md-nav__item">
|
||
<a href="#docforge.discover_module_paths" class="md-nav__link">
|
||
<span class="md-ellipsis">
|
||
discover_module_paths
|
||
</span>
|
||
</a>
|
||
|
||
</li>
|
||
|
||
</ul>
|
||
</nav>
|
||
|
||
</li>
|
||
|
||
</ul>
|
||
</nav>
|
||
|
||
</li>
|
||
|
||
</ul>
|
||
|
||
</nav>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
|
||
|
||
|
||
<div class="md-content" data-md-component="content">
|
||
<article class="md-content__inner md-typeset">
|
||
|
||
|
||
|
||
|
||
|
||
<h1 id="docforge_1">docforge</h1>
|
||
|
||
|
||
<div class="doc doc-object doc-module">
|
||
|
||
|
||
|
||
<h2 id="docforge" class="doc doc-heading">
|
||
<code class="doc-symbol doc-symbol-heading doc-symbol-module"></code> <span class="doc doc-object-name doc-module-name">docforge</span>
|
||
|
||
|
||
</h2>
|
||
|
||
<div class="doc doc-contents first">
|
||
|
||
<h3 id="docforge--summary">Summary</h3>
|
||
<p>Renderer-agnostic Python documentation compiler that converts Python docstrings
|
||
into structured documentation for both humans (MkDocs) and machines (MCP / AI agents).</p>
|
||
<p><code>doc-forge</code> statically analyzes source code, builds a semantic model of modules,
|
||
classes, functions, and attributes, and renders that model into documentation
|
||
outputs without executing user code.</p>
|
||
<hr />
|
||
<h3 id="docforge--installation">Installation</h3>
|
||
<p>Install using pip:</p>
|
||
<div class="language-bash highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span><span class="normal"><a href="#__codelineno-0-1">1</a></span></pre></div></td><td class="code"><div><pre><span></span><code><span id="__span-0-1"><a id="__codelineno-0-1" name="__codelineno-0-1"></a>pip<span class="w"> </span>install<span class="w"> </span>doc-forge
|
||
</span></code></pre></div></td></tr></table></div>
|
||
<hr />
|
||
<h3 id="docforge--cli-usage">CLI usage</h3>
|
||
<p>Each site kind (<code>lib</code>, <code>api</code>, <code>wiki</code>) is built independently into <code>site/{kind}</code>.</p>
|
||
<h4 id="docforge--build-the-library-reference-from-a-python-package">Build the library reference from a Python package:</h4>
|
||
<div class="language-bash highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span><span class="normal"><a href="#__codelineno-1-1">1</a></span></pre></div></td><td class="code"><div><pre><span></span><code><span id="__span-1-1"><a id="__codelineno-1-1" name="__codelineno-1-1"></a>doc-forge<span class="w"> </span>build<span class="w"> </span>--mkdocs<span class="w"> </span>--module<span class="w"> </span>my_package
|
||
</span></code></pre></div></td></tr></table></div>
|
||
<h4 id="docforge--build-the-api-reference-from-an-openapi-spec">Build the API reference from an OpenAPI spec:</h4>
|
||
<div class="language-bash highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span><span class="normal"><a href="#__codelineno-2-1">1</a></span></pre></div></td><td class="code"><div><pre><span></span><code><span id="__span-2-1"><a id="__codelineno-2-1" name="__codelineno-2-1"></a>doc-forge<span class="w"> </span>build<span class="w"> </span>--api<span class="w"> </span>--openapi-spec<span class="w"> </span>spec.json
|
||
</span></code></pre></div></td></tr></table></div>
|
||
<h4 id="docforge--build-the-hand-written-wiki">Build the hand-written wiki:</h4>
|
||
<div class="language-bash highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span><span class="normal"><a href="#__codelineno-3-1">1</a></span></pre></div></td><td class="code"><div><pre><span></span><code><span id="__span-3-1"><a id="__codelineno-3-1" name="__codelineno-3-1"></a>doc-forge<span class="w"> </span>build<span class="w"> </span>--wiki<span class="w"> </span>--site-name<span class="w"> </span>my_package
|
||
</span></code></pre></div></td></tr></table></div>
|
||
<h4 id="docforge--generate-mcp-json-documentation">Generate MCP JSON documentation:</h4>
|
||
<div class="language-bash highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span><span class="normal"><a href="#__codelineno-4-1">1</a></span></pre></div></td><td class="code"><div><pre><span></span><code><span id="__span-4-1"><a id="__codelineno-4-1" name="__codelineno-4-1"></a>doc-forge<span class="w"> </span>build<span class="w"> </span>--mcp<span class="w"> </span>--module<span class="w"> </span>my_package
|
||
</span></code></pre></div></td></tr></table></div>
|
||
<h4 id="docforge--build-several-kinds-in-one-pass">Build several kinds in one pass:</h4>
|
||
<div class="language-bash highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span><span class="normal"><a href="#__codelineno-5-1">1</a></span></pre></div></td><td class="code"><div><pre><span></span><code><span id="__span-5-1"><a id="__codelineno-5-1" name="__codelineno-5-1"></a>doc-forge<span class="w"> </span>build<span class="w"> </span>--mcp<span class="w"> </span>--mkdocs<span class="w"> </span>--wiki<span class="w"> </span>--module<span class="w"> </span>my_package
|
||
</span></code></pre></div></td></tr></table></div>
|
||
<p>Each enabled kind gets its own MkDocs config (<code>docs/mkdocs.{lib,api,wiki}.yml</code>)
|
||
and its own site under <code>site/</code>.</p>
|
||
<h4 id="docforge--serve-a-site-locally">Serve a site locally:</h4>
|
||
<div class="language-bash highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span><span class="normal"><a href="#__codelineno-6-1">1</a></span>
|
||
<span class="normal"><a href="#__codelineno-6-2">2</a></span>
|
||
<span class="normal"><a href="#__codelineno-6-3">3</a></span>
|
||
<span class="normal"><a href="#__codelineno-6-4">4</a></span>
|
||
<span class="normal"><a href="#__codelineno-6-5">5</a></span></pre></div></td><td class="code"><div><pre><span></span><code><span id="__span-6-1"><a id="__codelineno-6-1" name="__codelineno-6-1"></a>doc-forge<span class="w"> </span>serve<span class="w"> </span>--wiki<span class="w"> </span><span class="c1"># preview from docs/mkdocs.wiki.yml</span>
|
||
</span><span id="__span-6-2"><a id="__codelineno-6-2" name="__codelineno-6-2"></a>doc-forge<span class="w"> </span>serve<span class="w"> </span>--lib
|
||
</span><span id="__span-6-3"><a id="__codelineno-6-3" name="__codelineno-6-3"></a>doc-forge<span class="w"> </span>serve<span class="w"> </span>--api
|
||
</span><span id="__span-6-4"><a id="__codelineno-6-4" name="__codelineno-6-4"></a><span class="c1"># or any config directly:</span>
|
||
</span><span id="__span-6-5"><a id="__codelineno-6-5" name="__codelineno-6-5"></a>doc-forge<span class="w"> </span>serve<span class="w"> </span>--mkdocs<span class="w"> </span>--mkdocs-yml<span class="w"> </span>docs/mkdocs.wiki.yml
|
||
</span></code></pre></div></td></tr></table></div>
|
||
<h4 id="docforge--serve-mcp-locally">Serve MCP locally:</h4>
|
||
<div class="language-bash highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span><span class="normal"><a href="#__codelineno-7-1">1</a></span></pre></div></td><td class="code"><div><pre><span></span><code><span id="__span-7-1"><a id="__codelineno-7-1" name="__codelineno-7-1"></a>doc-forge<span class="w"> </span>serve<span class="w"> </span>--mcp<span class="w"> </span>--module<span class="w"> </span>my_package
|
||
</span></code></pre></div></td></tr></table></div>
|
||
<hr />
|
||
<h3 id="docforge--core-concepts">Core concepts</h3>
|
||
<h4 id="docforge--loader">Loader</h4>
|
||
<p>Extracts symbols, signatures, and docstrings using static analysis.</p>
|
||
<h4 id="docforge--semantic-model">Semantic model</h4>
|
||
<p>Structured, renderer-agnostic representation of the API.</p>
|
||
<h4 id="docforge--renderer">Renderer</h4>
|
||
<p>Converts the semantic model into output formats such as MkDocs or MCP JSON.</p>
|
||
<h4 id="docforge--symbol">Symbol</h4>
|
||
<p>Any documentable object</p>
|
||
<ul>
|
||
<li>module</li>
|
||
<li>class</li>
|
||
<li>function</li>
|
||
<li>method</li>
|
||
<li>property</li>
|
||
<li>attribute</li>
|
||
</ul>
|
||
<hr />
|
||
<h3 id="docforge--architecture">Architecture</h3>
|
||
<p><code>doc-forge</code> follows a compiler architecture:</p>
|
||
<h4 id="docforge--front-end">Front-end:</h4>
|
||
<p>Static analysis of modules, classes, functions, type hints, and docstrings.</p>
|
||
<h4 id="docforge--middle-end">Middle-end:</h4>
|
||
<p>Builds a semantic model describing symbols and relationships.</p>
|
||
<h4 id="docforge--back-end">Back-end:</h4>
|
||
<p>Renders documentation using interchangeable renderers.</p>
|
||
<p>This architecture ensures deterministic documentation generation.</p>
|
||
<hr />
|
||
<h3 id="docforge--rendering-pipeline">Rendering pipeline</h3>
|
||
<p>Typical flow:</p>
|
||
<div class="language-text highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span><span class="normal">1</span>
|
||
<span class="normal">2</span>
|
||
<span class="normal">3</span>
|
||
<span class="normal">4</span>
|
||
<span class="normal">5</span>
|
||
<span class="normal">6</span>
|
||
<span class="normal">7</span>
|
||
<span class="normal">8</span>
|
||
<span class="normal">9</span></pre></div></td><td class="code"><div><pre><span></span><code>Python package
|
||
|
|
||
Loader (static analysis)
|
||
|
|
||
Semantic model
|
||
|
|
||
Renderer
|
||
|
|
||
MkDocs site or MCP JSON
|
||
</code></pre></div></td></tr></table></div>
|
||
<hr />
|
||
<h3 id="docforge--google-styled-doc-forge-convention-gsdfc">Google-Styled Doc-Forge Convention (GSDFC)</h3>
|
||
<p>GSDFC defines how docstrings must be written so they render correctly in MkDocs and remain machine-parsable by doc-forge and AI tooling.</p>
|
||
<ul>
|
||
<li>Docstrings are the single source of truth.</li>
|
||
<li><code>doc-forge</code> compiles docstrings but does not generate documentation content.</li>
|
||
<li>Documentation follows the Python import hierarchy.</li>
|
||
<li>Every public symbol should have a complete and accurate docstring.</li>
|
||
</ul>
|
||
<hr />
|
||
<h4 id="docforge--general-rules">General rules</h4>
|
||
<ul>
|
||
<li>Use <strong>Markdown headings</strong> at package and module level.</li>
|
||
<li>Use <strong>Google-style structured sections</strong> at class, function, and method level.</li>
|
||
<li>Use type hints in signatures.</li>
|
||
<li>Use parenthesized types in prose entries (<code>name (Type):</code>) that match the
|
||
signature types. This keeps docstrings self-contained and machine-parseable.</li>
|
||
<li>Write summaries in imperative form.</li>
|
||
<li>Sections are separated by <code>---</code></li>
|
||
</ul>
|
||
<hr />
|
||
<h3 id="docforge--notes-subsection-grouping">Notes subsection grouping</h3>
|
||
<p>Group related information using labeled subsections.</p>
|
||
<p>Example:</p>
|
||
<div class="language-text highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span><span class="normal"> 1</span>
|
||
<span class="normal"> 2</span>
|
||
<span class="normal"> 3</span>
|
||
<span class="normal"> 4</span>
|
||
<span class="normal"> 5</span>
|
||
<span class="normal"> 6</span>
|
||
<span class="normal"> 7</span>
|
||
<span class="normal"> 8</span>
|
||
<span class="normal"> 9</span>
|
||
<span class="normal">10</span>
|
||
<span class="normal">11</span>
|
||
<span class="normal">12</span>
|
||
<span class="normal">13</span></pre></div></td><td class="code"><div><pre><span></span><code>Notes:
|
||
**Guarantees:**
|
||
|
||
- deterministic behavior
|
||
|
||
**Lifecycle:**
|
||
|
||
- created during initialization
|
||
- reused across executions
|
||
|
||
**Thread safety:**
|
||
|
||
- safe for concurrent reads
|
||
</code></pre></div></td></tr></table></div>
|
||
<hr />
|
||
<h3 id="docforge--example-formatting">Example formatting</h3>
|
||
<ul>
|
||
<li>Use indentation for examples.</li>
|
||
<li>Indent section contents using four spaces.</li>
|
||
<li>Use code blocks for example code.</li>
|
||
</ul>
|
||
|
||
|
||
<details class="example" open>
|
||
<summary>Example</summary>
|
||
<p>Single example:</p>
|
||
<div class="language-text highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span><span class="normal">1</span>
|
||
<span class="normal">2</span>
|
||
<span class="normal">3</span>
|
||
<span class="normal">4</span>
|
||
<span class="normal">5</span>
|
||
<span class="normal">6</span></pre></div></td><td class="code"><div><pre><span></span><code>Example:
|
||
|
||
```python
|
||
foo = Foo("example")
|
||
process(foo, multiplier=2)
|
||
```
|
||
</code></pre></div></td></tr></table></div>
|
||
<p>Multiple examples:</p>
|
||
<div class="language-text highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span><span class="normal"> 1</span>
|
||
<span class="normal"> 2</span>
|
||
<span class="normal"> 3</span>
|
||
<span class="normal"> 4</span>
|
||
<span class="normal"> 5</span>
|
||
<span class="normal"> 6</span>
|
||
<span class="normal"> 7</span>
|
||
<span class="normal"> 8</span>
|
||
<span class="normal"> 9</span>
|
||
<span class="normal">10</span>
|
||
<span class="normal">11</span>
|
||
<span class="normal">12</span>
|
||
<span class="normal">13</span></pre></div></td><td class="code"><div><pre><span></span><code>Example:
|
||
Create foo:
|
||
|
||
```python
|
||
foo = Foo("example")
|
||
```
|
||
|
||
Run engine:
|
||
|
||
```python
|
||
engine = BarEngine([foo])
|
||
engine.run()
|
||
```
|
||
</code></pre></div></td></tr></table></div>
|
||
</details> <p>Avoid fenced code blocks inside argument descriptions and other prose lines.</p>
|
||
<p>Inside <code>Example:</code> sections, fenced <code>python</code> code blocks are allowed and must be
|
||
indented four spaces, matching the examples below.</p>
|
||
<hr />
|
||
<h3 id="docforge--separator-rules">Separator rules</h3>
|
||
<p>Use horizontal separators only at docstring root level to separate sections:</p>
|
||
<div class="language-markdown highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span><span class="normal"><a href="#__codelineno-0-1">1</a></span></pre></div></td><td class="code"><div><pre><span></span><code><span id="__span-0-1"><a id="__codelineno-0-1" name="__codelineno-0-1"></a>---
|
||
</span></code></pre></div></td></tr></table></div>
|
||
<p>Allowed locations:</p>
|
||
<ul>
|
||
<li>package docstrings</li>
|
||
<li>module docstrings</li>
|
||
<li>major documentation sections</li>
|
||
</ul>
|
||
<p>Do not use separators inside code sections.</p>
|
||
<hr />
|
||
<h3 id="docforge--package-docstrings">Package docstrings</h3>
|
||
<p>Package docstrings act as the documentation home page.</p>
|
||
<p>Recommended sections:</p>
|
||
<div class="language-text highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span><span class="normal">1</span>
|
||
<span class="normal">2</span>
|
||
<span class="normal">3</span>
|
||
<span class="normal">4</span>
|
||
<span class="normal">5</span>
|
||
<span class="normal">6</span>
|
||
<span class="normal">7</span>
|
||
<span class="normal">8</span>
|
||
<span class="normal">9</span></pre></div></td><td class="code"><div><pre><span></span><code># Summary
|
||
# Installation
|
||
# Quick start
|
||
# CLI usage
|
||
# Core concepts
|
||
# Architecture
|
||
# Rendering pipeline
|
||
# Examples
|
||
# Notes
|
||
</code></pre></div></td></tr></table></div>
|
||
|
||
|
||
<details class="example" open>
|
||
<summary>Example</summary>
|
||
<p>Package Doc String:</p>
|
||
<div class="language-text highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span><span class="normal"> 1</span>
|
||
<span class="normal"> 2</span>
|
||
<span class="normal"> 3</span>
|
||
<span class="normal"> 4</span>
|
||
<span class="normal"> 5</span>
|
||
<span class="normal"> 6</span>
|
||
<span class="normal"> 7</span>
|
||
<span class="normal"> 8</span>
|
||
<span class="normal"> 9</span>
|
||
<span class="normal">10</span>
|
||
<span class="normal">11</span>
|
||
<span class="normal">12</span>
|
||
<span class="normal">13</span>
|
||
<span class="normal">14</span>
|
||
<span class="normal">15</span>
|
||
<span class="normal">16</span>
|
||
<span class="normal">17</span>
|
||
<span class="normal">18</span>
|
||
<span class="normal">19</span>
|
||
<span class="normal">20</span>
|
||
<span class="normal">21</span>
|
||
<span class="normal">22</span>
|
||
<span class="normal">23</span>
|
||
<span class="normal">24</span>
|
||
<span class="normal">25</span>
|
||
<span class="normal">26</span>
|
||
<span class="normal">27</span>
|
||
<span class="normal">28</span>
|
||
<span class="normal">29</span>
|
||
<span class="normal">30</span></pre></div></td><td class="code"><div><pre><span></span><code>'''
|
||
# Summary
|
||
|
||
Foo-bar processing framework.
|
||
|
||
Provides tools for defining Foo objects and executing Bar pipelines.
|
||
|
||
---
|
||
|
||
# Installation
|
||
|
||
```bash
|
||
pip install foo-bar
|
||
```
|
||
|
||
---
|
||
|
||
# Quick start
|
||
|
||
```python
|
||
from foobar import Foo, BarEngine
|
||
|
||
foo = Foo("example")
|
||
engine = BarEngine([foo])
|
||
|
||
result = engine.run()
|
||
```
|
||
|
||
---
|
||
'''
|
||
</code></pre></div></td></tr></table></div>
|
||
</details> <hr />
|
||
<h3 id="docforge--module-docstrings">Module docstrings</h3>
|
||
<p>Module docstrings describe a subsystem.</p>
|
||
<p>Recommended sections:</p>
|
||
<div class="language-text highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span><span class="normal">1</span>
|
||
<span class="normal">2</span>
|
||
<span class="normal">3</span></pre></div></td><td class="code"><div><pre><span></span><code># Summary
|
||
# Examples
|
||
# Notes
|
||
</code></pre></div></td></tr></table></div>
|
||
|
||
|
||
<details class="example" open>
|
||
<summary>Example</summary>
|
||
<p>Module Doc String:</p>
|
||
<div class="language-text highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span><span class="normal"> 1</span>
|
||
<span class="normal"> 2</span>
|
||
<span class="normal"> 3</span>
|
||
<span class="normal"> 4</span>
|
||
<span class="normal"> 5</span>
|
||
<span class="normal"> 6</span>
|
||
<span class="normal"> 7</span>
|
||
<span class="normal"> 8</span>
|
||
<span class="normal"> 9</span>
|
||
<span class="normal">10</span>
|
||
<span class="normal">11</span>
|
||
<span class="normal">12</span>
|
||
<span class="normal">13</span>
|
||
<span class="normal">14</span>
|
||
<span class="normal">15</span>
|
||
<span class="normal">16</span>
|
||
<span class="normal">17</span>
|
||
<span class="normal">18</span>
|
||
<span class="normal">19</span>
|
||
<span class="normal">20</span>
|
||
<span class="normal">21</span>
|
||
<span class="normal">22</span>
|
||
<span class="normal">23</span></pre></div></td><td class="code"><div><pre><span></span><code>'''
|
||
# Summary
|
||
|
||
Foo execution subsystem.
|
||
|
||
Provides utilities for executing Foo objects through Bar stages.
|
||
|
||
---
|
||
|
||
Example:
|
||
|
||
```python
|
||
from foobar.engine import BarEngine
|
||
from foobar.foo import Foo
|
||
|
||
foo = Foo("example")
|
||
|
||
engine = BarEngine([foo])
|
||
engine.run()
|
||
```
|
||
|
||
---
|
||
'''
|
||
</code></pre></div></td></tr></table></div>
|
||
</details> <hr />
|
||
<h3 id="docforge--class-docstrings">Class docstrings</h3>
|
||
<p>Class docstrings define object responsibility, lifecycle, and attributes.</p>
|
||
<p>Recommended sections:</p>
|
||
<div class="language-text highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span><span class="normal">1</span>
|
||
<span class="normal">2</span>
|
||
<span class="normal">3</span>
|
||
<span class="normal">4</span></pre></div></td><td class="code"><div><pre><span></span><code>Attributes:
|
||
Notes:
|
||
Example:
|
||
Raises:
|
||
</code></pre></div></td></tr></table></div>
|
||
|
||
|
||
<details class="example" open>
|
||
<summary>Example</summary>
|
||
<p>Simple Foo:</p>
|
||
<div class="language-python highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span><span class="normal"><a href="#__codelineno-0-1"> 1</a></span>
|
||
<span class="normal"><a href="#__codelineno-0-2"> 2</a></span>
|
||
<span class="normal"><a href="#__codelineno-0-3"> 3</a></span>
|
||
<span class="normal"><a href="#__codelineno-0-4"> 4</a></span>
|
||
<span class="normal"><a href="#__codelineno-0-5"> 5</a></span>
|
||
<span class="normal"><a href="#__codelineno-0-6"> 6</a></span>
|
||
<span class="normal"><a href="#__codelineno-0-7"> 7</a></span>
|
||
<span class="normal"><a href="#__codelineno-0-8"> 8</a></span>
|
||
<span class="normal"><a href="#__codelineno-0-9"> 9</a></span>
|
||
<span class="normal"><a href="#__codelineno-0-10">10</a></span>
|
||
<span class="normal"><a href="#__codelineno-0-11">11</a></span>
|
||
<span class="normal"><a href="#__codelineno-0-12">12</a></span>
|
||
<span class="normal"><a href="#__codelineno-0-13">13</a></span>
|
||
<span class="normal"><a href="#__codelineno-0-14">14</a></span>
|
||
<span class="normal"><a href="#__codelineno-0-15">15</a></span>
|
||
<span class="normal"><a href="#__codelineno-0-16">16</a></span>
|
||
<span class="normal"><a href="#__codelineno-0-17">17</a></span>
|
||
<span class="normal"><a href="#__codelineno-0-18">18</a></span>
|
||
<span class="normal"><a href="#__codelineno-0-19">19</a></span>
|
||
<span class="normal"><a href="#__codelineno-0-20">20</a></span>
|
||
<span class="normal"><a href="#__codelineno-0-21">21</a></span>
|
||
<span class="normal"><a href="#__codelineno-0-22">22</a></span>
|
||
<span class="normal"><a href="#__codelineno-0-23">23</a></span>
|
||
<span class="normal"><a href="#__codelineno-0-24">24</a></span>
|
||
<span class="normal"><a href="#__codelineno-0-25">25</a></span>
|
||
<span class="normal"><a href="#__codelineno-0-26">26</a></span>
|
||
<span class="normal"><a href="#__codelineno-0-27">27</a></span>
|
||
<span class="normal"><a href="#__codelineno-0-28">28</a></span>
|
||
<span class="normal"><a href="#__codelineno-0-29">29</a></span></pre></div></td><td class="code"><div><pre><span></span><code><span id="__span-0-1"><a id="__codelineno-0-1" name="__codelineno-0-1"></a><span class="k">class</span><span class="w"> </span><span class="nc">Foo</span><span class="p">:</span>
|
||
</span><span id="__span-0-2"><a id="__codelineno-0-2" name="__codelineno-0-2"></a><span class="w"> </span><span class="sd">'''</span>
|
||
</span><span id="__span-0-3"><a id="__codelineno-0-3" name="__codelineno-0-3"></a><span class="sd"> Represents a unit of work.</span>
|
||
</span><span id="__span-0-4"><a id="__codelineno-0-4" name="__codelineno-0-4"></a>
|
||
</span><span id="__span-0-5"><a id="__codelineno-0-5" name="__codelineno-0-5"></a><span class="sd"> Attributes:</span>
|
||
</span><span id="__span-0-6"><a id="__codelineno-0-6" name="__codelineno-0-6"></a><span class="sd"> name (str):</span>
|
||
</span><span id="__span-0-7"><a id="__codelineno-0-7" name="__codelineno-0-7"></a><span class="sd"> Identifier of the foo instance.</span>
|
||
</span><span id="__span-0-8"><a id="__codelineno-0-8" name="__codelineno-0-8"></a>
|
||
</span><span id="__span-0-9"><a id="__codelineno-0-9" name="__codelineno-0-9"></a><span class="sd"> value (int):</span>
|
||
</span><span id="__span-0-10"><a id="__codelineno-0-10" name="__codelineno-0-10"></a><span class="sd"> Numeric value associated with foo.</span>
|
||
</span><span id="__span-0-11"><a id="__codelineno-0-11" name="__codelineno-0-11"></a>
|
||
</span><span id="__span-0-12"><a id="__codelineno-0-12" name="__codelineno-0-12"></a><span class="sd"> Notes:</span>
|
||
</span><span id="__span-0-13"><a id="__codelineno-0-13" name="__codelineno-0-13"></a><span class="sd"> Guarantees:</span>
|
||
</span><span id="__span-0-14"><a id="__codelineno-0-14" name="__codelineno-0-14"></a>
|
||
</span><span id="__span-0-15"><a id="__codelineno-0-15" name="__codelineno-0-15"></a><span class="sd"> - instances are immutable after creation</span>
|
||
</span><span id="__span-0-16"><a id="__codelineno-0-16" name="__codelineno-0-16"></a>
|
||
</span><span id="__span-0-17"><a id="__codelineno-0-17" name="__codelineno-0-17"></a><span class="sd"> Lifecycle:</span>
|
||
</span><span id="__span-0-18"><a id="__codelineno-0-18" name="__codelineno-0-18"></a>
|
||
</span><span id="__span-0-19"><a id="__codelineno-0-19" name="__codelineno-0-19"></a><span class="sd"> - create instance</span>
|
||
</span><span id="__span-0-20"><a id="__codelineno-0-20" name="__codelineno-0-20"></a><span class="sd"> - pass to processing engine</span>
|
||
</span><span id="__span-0-21"><a id="__codelineno-0-21" name="__codelineno-0-21"></a>
|
||
</span><span id="__span-0-22"><a id="__codelineno-0-22" name="__codelineno-0-22"></a><span class="sd"> Example:</span>
|
||
</span><span id="__span-0-23"><a id="__codelineno-0-23" name="__codelineno-0-23"></a><span class="sd"> Create and inspect a Foo:</span>
|
||
</span><span id="__span-0-24"><a id="__codelineno-0-24" name="__codelineno-0-24"></a>
|
||
</span><span id="__span-0-25"><a id="__codelineno-0-25" name="__codelineno-0-25"></a><span class="sd"> ```python</span>
|
||
</span><span id="__span-0-26"><a id="__codelineno-0-26" name="__codelineno-0-26"></a><span class="sd"> foo = Foo("example", value=42)</span>
|
||
</span><span id="__span-0-27"><a id="__codelineno-0-27" name="__codelineno-0-27"></a><span class="sd"> print(foo.name)</span>
|
||
</span><span id="__span-0-28"><a id="__codelineno-0-28" name="__codelineno-0-28"></a><span class="sd"> ```</span>
|
||
</span><span id="__span-0-29"><a id="__codelineno-0-29" name="__codelineno-0-29"></a><span class="sd"> '''</span>
|
||
</span></code></pre></div></td></tr></table></div>
|
||
<p>Complex Bar:</p>
|
||
<div class="language-python highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span><span class="normal"><a href="#__codelineno-1-1"> 1</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-2"> 2</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-3"> 3</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-4"> 4</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-5"> 5</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-6"> 6</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-7"> 7</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-8"> 8</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-9"> 9</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-10">10</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-11">11</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-12">12</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-13">13</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-14">14</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-15">15</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-16">16</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-17">17</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-18">18</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-19">19</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-20">20</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-21">21</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-22">22</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-23">23</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-24">24</a></span></pre></div></td><td class="code"><div><pre><span></span><code><span id="__span-1-1"><a id="__codelineno-1-1" name="__codelineno-1-1"></a><span class="k">class</span><span class="w"> </span><span class="nc">BarEngine</span><span class="p">:</span>
|
||
</span><span id="__span-1-2"><a id="__codelineno-1-2" name="__codelineno-1-2"></a><span class="w"> </span><span class="sd">'''</span>
|
||
</span><span id="__span-1-3"><a id="__codelineno-1-3" name="__codelineno-1-3"></a><span class="sd"> Executes Foo objects through Bar stages.</span>
|
||
</span><span id="__span-1-4"><a id="__codelineno-1-4" name="__codelineno-1-4"></a>
|
||
</span><span id="__span-1-5"><a id="__codelineno-1-5" name="__codelineno-1-5"></a><span class="sd"> Attributes:</span>
|
||
</span><span id="__span-1-6"><a id="__codelineno-1-6" name="__codelineno-1-6"></a><span class="sd"> foos (tuple[Foo, ...]):</span>
|
||
</span><span id="__span-1-7"><a id="__codelineno-1-7" name="__codelineno-1-7"></a><span class="sd"> Foo instances managed by the engine.</span>
|
||
</span><span id="__span-1-8"><a id="__codelineno-1-8" name="__codelineno-1-8"></a>
|
||
</span><span id="__span-1-9"><a id="__codelineno-1-9" name="__codelineno-1-9"></a><span class="sd"> Notes:</span>
|
||
</span><span id="__span-1-10"><a id="__codelineno-1-10" name="__codelineno-1-10"></a><span class="sd"> Guarantees:</span>
|
||
</span><span id="__span-1-11"><a id="__codelineno-1-11" name="__codelineno-1-11"></a>
|
||
</span><span id="__span-1-12"><a id="__codelineno-1-12" name="__codelineno-1-12"></a><span class="sd"> - deterministic execution order</span>
|
||
</span><span id="__span-1-13"><a id="__codelineno-1-13" name="__codelineno-1-13"></a>
|
||
</span><span id="__span-1-14"><a id="__codelineno-1-14" name="__codelineno-1-14"></a><span class="sd"> Example:</span>
|
||
</span><span id="__span-1-15"><a id="__codelineno-1-15" name="__codelineno-1-15"></a><span class="sd"> Run engine:</span>
|
||
</span><span id="__span-1-16"><a id="__codelineno-1-16" name="__codelineno-1-16"></a>
|
||
</span><span id="__span-1-17"><a id="__codelineno-1-17" name="__codelineno-1-17"></a><span class="sd"> ```python</span>
|
||
</span><span id="__span-1-18"><a id="__codelineno-1-18" name="__codelineno-1-18"></a><span class="sd"> foo1 = Foo("a")</span>
|
||
</span><span id="__span-1-19"><a id="__codelineno-1-19" name="__codelineno-1-19"></a><span class="sd"> foo2 = Foo("b")</span>
|
||
</span><span id="__span-1-20"><a id="__codelineno-1-20" name="__codelineno-1-20"></a>
|
||
</span><span id="__span-1-21"><a id="__codelineno-1-21" name="__codelineno-1-21"></a><span class="sd"> engine = BarEngine([foo1, foo2])</span>
|
||
</span><span id="__span-1-22"><a id="__codelineno-1-22" name="__codelineno-1-22"></a><span class="sd"> engine.run()</span>
|
||
</span><span id="__span-1-23"><a id="__codelineno-1-23" name="__codelineno-1-23"></a><span class="sd"> ```</span>
|
||
</span><span id="__span-1-24"><a id="__codelineno-1-24" name="__codelineno-1-24"></a><span class="sd"> '''</span>
|
||
</span></code></pre></div></td></tr></table></div>
|
||
</details> <hr />
|
||
<h3 id="docforge--function-and-method-docstrings">Function and method docstrings</h3>
|
||
<p>Function docstrings define API contracts.</p>
|
||
<p>Recommended sections:</p>
|
||
<div class="language-text highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span><span class="normal">1</span>
|
||
<span class="normal">2</span>
|
||
<span class="normal">3</span>
|
||
<span class="normal">4</span>
|
||
<span class="normal">5</span>
|
||
<span class="normal">6</span></pre></div></td><td class="code"><div><pre><span></span><code>Args:
|
||
Returns:
|
||
Raises:
|
||
Yields:
|
||
Notes:
|
||
Example:
|
||
</code></pre></div></td></tr></table></div>
|
||
|
||
|
||
<details class="example" open>
|
||
<summary>Example</summary>
|
||
<p>Simple process method:</p>
|
||
<div class="language-python highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span><span class="normal"><a href="#__codelineno-0-1"> 1</a></span>
|
||
<span class="normal"><a href="#__codelineno-0-2"> 2</a></span>
|
||
<span class="normal"><a href="#__codelineno-0-3"> 3</a></span>
|
||
<span class="normal"><a href="#__codelineno-0-4"> 4</a></span>
|
||
<span class="normal"><a href="#__codelineno-0-5"> 5</a></span>
|
||
<span class="normal"><a href="#__codelineno-0-6"> 6</a></span>
|
||
<span class="normal"><a href="#__codelineno-0-7"> 7</a></span>
|
||
<span class="normal"><a href="#__codelineno-0-8"> 8</a></span>
|
||
<span class="normal"><a href="#__codelineno-0-9"> 9</a></span>
|
||
<span class="normal"><a href="#__codelineno-0-10">10</a></span>
|
||
<span class="normal"><a href="#__codelineno-0-11">11</a></span>
|
||
<span class="normal"><a href="#__codelineno-0-12">12</a></span>
|
||
<span class="normal"><a href="#__codelineno-0-13">13</a></span>
|
||
<span class="normal"><a href="#__codelineno-0-14">14</a></span>
|
||
<span class="normal"><a href="#__codelineno-0-15">15</a></span>
|
||
<span class="normal"><a href="#__codelineno-0-16">16</a></span>
|
||
<span class="normal"><a href="#__codelineno-0-17">17</a></span>
|
||
<span class="normal"><a href="#__codelineno-0-18">18</a></span>
|
||
<span class="normal"><a href="#__codelineno-0-19">19</a></span>
|
||
<span class="normal"><a href="#__codelineno-0-20">20</a></span>
|
||
<span class="normal"><a href="#__codelineno-0-21">21</a></span>
|
||
<span class="normal"><a href="#__codelineno-0-22">22</a></span>
|
||
<span class="normal"><a href="#__codelineno-0-23">23</a></span>
|
||
<span class="normal"><a href="#__codelineno-0-24">24</a></span>
|
||
<span class="normal"><a href="#__codelineno-0-25">25</a></span>
|
||
<span class="normal"><a href="#__codelineno-0-26">26</a></span>
|
||
<span class="normal"><a href="#__codelineno-0-27">27</a></span>
|
||
<span class="normal"><a href="#__codelineno-0-28">28</a></span>
|
||
<span class="normal"><a href="#__codelineno-0-29">29</a></span>
|
||
<span class="normal"><a href="#__codelineno-0-30">30</a></span>
|
||
<span class="normal"><a href="#__codelineno-0-31">31</a></span>
|
||
<span class="normal"><a href="#__codelineno-0-32">32</a></span>
|
||
<span class="normal"><a href="#__codelineno-0-33">33</a></span>
|
||
<span class="normal"><a href="#__codelineno-0-34">34</a></span></pre></div></td><td class="code"><div><pre><span></span><code><span id="__span-0-1"><a id="__codelineno-0-1" name="__codelineno-0-1"></a><span class="k">def</span><span class="w"> </span><span class="nf">process</span><span class="p">(</span><span class="n">foo</span><span class="p">:</span> <span class="n">Foo</span><span class="p">,</span> <span class="n">multiplier</span><span class="p">:</span> <span class="nb">int</span><span class="p">)</span> <span class="o">-></span> <span class="nb">int</span><span class="p">:</span>
|
||
</span><span id="__span-0-2"><a id="__codelineno-0-2" name="__codelineno-0-2"></a><span class="w"> </span><span class="sd">'''</span>
|
||
</span><span id="__span-0-3"><a id="__codelineno-0-3" name="__codelineno-0-3"></a><span class="sd"> Process a Foo instance.</span>
|
||
</span><span id="__span-0-4"><a id="__codelineno-0-4" name="__codelineno-0-4"></a>
|
||
</span><span id="__span-0-5"><a id="__codelineno-0-5" name="__codelineno-0-5"></a><span class="sd"> Args:</span>
|
||
</span><span id="__span-0-6"><a id="__codelineno-0-6" name="__codelineno-0-6"></a><span class="sd"> foo (Foo):</span>
|
||
</span><span id="__span-0-7"><a id="__codelineno-0-7" name="__codelineno-0-7"></a><span class="sd"> Foo instance to process.</span>
|
||
</span><span id="__span-0-8"><a id="__codelineno-0-8" name="__codelineno-0-8"></a>
|
||
</span><span id="__span-0-9"><a id="__codelineno-0-9" name="__codelineno-0-9"></a><span class="sd"> multiplier (int):</span>
|
||
</span><span id="__span-0-10"><a id="__codelineno-0-10" name="__codelineno-0-10"></a><span class="sd"> Value used to scale foo.</span>
|
||
</span><span id="__span-0-11"><a id="__codelineno-0-11" name="__codelineno-0-11"></a>
|
||
</span><span id="__span-0-12"><a id="__codelineno-0-12" name="__codelineno-0-12"></a><span class="sd"> Returns:</span>
|
||
</span><span id="__span-0-13"><a id="__codelineno-0-13" name="__codelineno-0-13"></a><span class="sd"> int:</span>
|
||
</span><span id="__span-0-14"><a id="__codelineno-0-14" name="__codelineno-0-14"></a><span class="sd"> Processed result.</span>
|
||
</span><span id="__span-0-15"><a id="__codelineno-0-15" name="__codelineno-0-15"></a>
|
||
</span><span id="__span-0-16"><a id="__codelineno-0-16" name="__codelineno-0-16"></a><span class="sd"> Raises:</span>
|
||
</span><span id="__span-0-17"><a id="__codelineno-0-17" name="__codelineno-0-17"></a><span class="sd"> ValueError:</span>
|
||
</span><span id="__span-0-18"><a id="__codelineno-0-18" name="__codelineno-0-18"></a><span class="sd"> If multiplier is negative.</span>
|
||
</span><span id="__span-0-19"><a id="__codelineno-0-19" name="__codelineno-0-19"></a>
|
||
</span><span id="__span-0-20"><a id="__codelineno-0-20" name="__codelineno-0-20"></a><span class="sd"> Notes:</span>
|
||
</span><span id="__span-0-21"><a id="__codelineno-0-21" name="__codelineno-0-21"></a><span class="sd"> Guarantees:</span>
|
||
</span><span id="__span-0-22"><a id="__codelineno-0-22" name="__codelineno-0-22"></a>
|
||
</span><span id="__span-0-23"><a id="__codelineno-0-23" name="__codelineno-0-23"></a><span class="sd"> - foo is not modified</span>
|
||
</span><span id="__span-0-24"><a id="__codelineno-0-24" name="__codelineno-0-24"></a>
|
||
</span><span id="__span-0-25"><a id="__codelineno-0-25" name="__codelineno-0-25"></a><span class="sd"> Example:</span>
|
||
</span><span id="__span-0-26"><a id="__codelineno-0-26" name="__codelineno-0-26"></a><span class="sd"> Process foo:</span>
|
||
</span><span id="__span-0-27"><a id="__codelineno-0-27" name="__codelineno-0-27"></a>
|
||
</span><span id="__span-0-28"><a id="__codelineno-0-28" name="__codelineno-0-28"></a><span class="sd"> ```python</span>
|
||
</span><span id="__span-0-29"><a id="__codelineno-0-29" name="__codelineno-0-29"></a><span class="sd"> foo = Foo("example", value=10)</span>
|
||
</span><span id="__span-0-30"><a id="__codelineno-0-30" name="__codelineno-0-30"></a>
|
||
</span><span id="__span-0-31"><a id="__codelineno-0-31" name="__codelineno-0-31"></a><span class="sd"> result = process(foo, multiplier=2)</span>
|
||
</span><span id="__span-0-32"><a id="__codelineno-0-32" name="__codelineno-0-32"></a><span class="sd"> print(result)</span>
|
||
</span><span id="__span-0-33"><a id="__codelineno-0-33" name="__codelineno-0-33"></a><span class="sd"> ```</span>
|
||
</span><span id="__span-0-34"><a id="__codelineno-0-34" name="__codelineno-0-34"></a><span class="sd"> '''</span>
|
||
</span></code></pre></div></td></tr></table></div>
|
||
<p>Multiple Examples:</p>
|
||
<div class="language-python highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span><span class="normal"><a href="#__codelineno-1-1"> 1</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-2"> 2</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-3"> 3</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-4"> 4</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-5"> 5</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-6"> 6</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-7"> 7</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-8"> 8</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-9"> 9</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-10">10</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-11">11</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-12">12</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-13">13</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-14">14</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-15">15</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-16">16</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-17">17</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-18">18</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-19">19</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-20">20</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-21">21</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-22">22</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-23">23</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-24">24</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-25">25</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-26">26</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-27">27</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-28">28</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-29">29</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-30">30</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-31">31</a></span>
|
||
<span class="normal"><a href="#__codelineno-1-32">32</a></span></pre></div></td><td class="code"><div><pre><span></span><code><span id="__span-1-1"><a id="__codelineno-1-1" name="__codelineno-1-1"></a><span class="k">def</span><span class="w"> </span><span class="nf">combine</span><span class="p">(</span><span class="n">foo_a</span><span class="p">:</span> <span class="n">Foo</span><span class="p">,</span> <span class="n">foo_b</span><span class="p">:</span> <span class="n">Foo</span><span class="p">)</span> <span class="o">-></span> <span class="n">Foo</span><span class="p">:</span>
|
||
</span><span id="__span-1-2"><a id="__codelineno-1-2" name="__codelineno-1-2"></a><span class="w"> </span><span class="sd">'''</span>
|
||
</span><span id="__span-1-3"><a id="__codelineno-1-3" name="__codelineno-1-3"></a><span class="sd"> Combine two Foo instances.</span>
|
||
</span><span id="__span-1-4"><a id="__codelineno-1-4" name="__codelineno-1-4"></a>
|
||
</span><span id="__span-1-5"><a id="__codelineno-1-5" name="__codelineno-1-5"></a><span class="sd"> Args:</span>
|
||
</span><span id="__span-1-6"><a id="__codelineno-1-6" name="__codelineno-1-6"></a><span class="sd"> foo_a (Foo):</span>
|
||
</span><span id="__span-1-7"><a id="__codelineno-1-7" name="__codelineno-1-7"></a><span class="sd"> First foo.</span>
|
||
</span><span id="__span-1-8"><a id="__codelineno-1-8" name="__codelineno-1-8"></a>
|
||
</span><span id="__span-1-9"><a id="__codelineno-1-9" name="__codelineno-1-9"></a><span class="sd"> foo_b (Foo):</span>
|
||
</span><span id="__span-1-10"><a id="__codelineno-1-10" name="__codelineno-1-10"></a><span class="sd"> Second foo.</span>
|
||
</span><span id="__span-1-11"><a id="__codelineno-1-11" name="__codelineno-1-11"></a>
|
||
</span><span id="__span-1-12"><a id="__codelineno-1-12" name="__codelineno-1-12"></a><span class="sd"> Returns:</span>
|
||
</span><span id="__span-1-13"><a id="__codelineno-1-13" name="__codelineno-1-13"></a><span class="sd"> Foo:</span>
|
||
</span><span id="__span-1-14"><a id="__codelineno-1-14" name="__codelineno-1-14"></a><span class="sd"> Combined foo.</span>
|
||
</span><span id="__span-1-15"><a id="__codelineno-1-15" name="__codelineno-1-15"></a>
|
||
</span><span id="__span-1-16"><a id="__codelineno-1-16" name="__codelineno-1-16"></a><span class="sd"> Example:</span>
|
||
</span><span id="__span-1-17"><a id="__codelineno-1-17" name="__codelineno-1-17"></a><span class="sd"> Basic usage:</span>
|
||
</span><span id="__span-1-18"><a id="__codelineno-1-18" name="__codelineno-1-18"></a>
|
||
</span><span id="__span-1-19"><a id="__codelineno-1-19" name="__codelineno-1-19"></a><span class="sd"> ```python</span>
|
||
</span><span id="__span-1-20"><a id="__codelineno-1-20" name="__codelineno-1-20"></a><span class="sd"> foo1 = Foo("a")</span>
|
||
</span><span id="__span-1-21"><a id="__codelineno-1-21" name="__codelineno-1-21"></a><span class="sd"> foo2 = Foo("b")</span>
|
||
</span><span id="__span-1-22"><a id="__codelineno-1-22" name="__codelineno-1-22"></a>
|
||
</span><span id="__span-1-23"><a id="__codelineno-1-23" name="__codelineno-1-23"></a><span class="sd"> combined = combine(foo1, foo2)</span>
|
||
</span><span id="__span-1-24"><a id="__codelineno-1-24" name="__codelineno-1-24"></a><span class="sd"> ```</span>
|
||
</span><span id="__span-1-25"><a id="__codelineno-1-25" name="__codelineno-1-25"></a>
|
||
</span><span id="__span-1-26"><a id="__codelineno-1-26" name="__codelineno-1-26"></a><span class="sd"> Pipeline usage:</span>
|
||
</span><span id="__span-1-27"><a id="__codelineno-1-27" name="__codelineno-1-27"></a>
|
||
</span><span id="__span-1-28"><a id="__codelineno-1-28" name="__codelineno-1-28"></a><span class="sd"> ```python</span>
|
||
</span><span id="__span-1-29"><a id="__codelineno-1-29" name="__codelineno-1-29"></a><span class="sd"> engine = BarEngine([foo1, foo2])</span>
|
||
</span><span id="__span-1-30"><a id="__codelineno-1-30" name="__codelineno-1-30"></a><span class="sd"> engine.run()</span>
|
||
</span><span id="__span-1-31"><a id="__codelineno-1-31" name="__codelineno-1-31"></a><span class="sd"> ```</span>
|
||
</span><span id="__span-1-32"><a id="__codelineno-1-32" name="__codelineno-1-32"></a><span class="sd"> '''</span>
|
||
</span></code></pre></div></td></tr></table></div>
|
||
</details> <hr />
|
||
<h3 id="docforge--property-docstrings">Property docstrings</h3>
|
||
<p>Properties must document return values.</p>
|
||
|
||
|
||
<details class="example" open>
|
||
<summary>Example</summary>
|
||
<p>Property Doc String:</p>
|
||
<div class="language-text highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span><span class="normal"> 1</span>
|
||
<span class="normal"> 2</span>
|
||
<span class="normal"> 3</span>
|
||
<span class="normal"> 4</span>
|
||
<span class="normal"> 5</span>
|
||
<span class="normal"> 6</span>
|
||
<span class="normal"> 7</span>
|
||
<span class="normal"> 8</span>
|
||
<span class="normal"> 9</span>
|
||
<span class="normal">10</span>
|
||
<span class="normal">11</span>
|
||
<span class="normal">12</span>
|
||
<span class="normal">13</span>
|
||
<span class="normal">14</span>
|
||
<span class="normal">15</span>
|
||
<span class="normal">16</span>
|
||
<span class="normal">17</span>
|
||
<span class="normal">18</span></pre></div></td><td class="code"><div><pre><span></span><code>```python
|
||
@property
|
||
def foos(self) -> tuple[Foo, ...]:
|
||
'''
|
||
Return contained Foo instances.
|
||
|
||
Returns:
|
||
tuple[Foo, ...]:
|
||
Stored foo objects.
|
||
|
||
Example:
|
||
```python
|
||
container = FooContainer()
|
||
|
||
foos = container.foos
|
||
```
|
||
'''
|
||
```
|
||
</code></pre></div></td></tr></table></div>
|
||
</details> <hr />
|
||
<h3 id="docforge--attribute-documentation">Attribute documentation</h3>
|
||
<p>Document attributes in class docstrings using <code>Attributes:</code>.</p>
|
||
|
||
|
||
<details class="example" open>
|
||
<summary>Example</summary>
|
||
<p>Attribute Doc String:</p>
|
||
<div class="language-text highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span><span class="normal"> 1</span>
|
||
<span class="normal"> 2</span>
|
||
<span class="normal"> 3</span>
|
||
<span class="normal"> 4</span>
|
||
<span class="normal"> 5</span>
|
||
<span class="normal"> 6</span>
|
||
<span class="normal"> 7</span>
|
||
<span class="normal"> 8</span>
|
||
<span class="normal"> 9</span>
|
||
<span class="normal">10</span>
|
||
<span class="normal">11</span>
|
||
<span class="normal">12</span></pre></div></td><td class="code"><div><pre><span></span><code>```python
|
||
'''
|
||
Represents a processing stage.
|
||
|
||
Attributes:
|
||
id (str):
|
||
Unique identifier.
|
||
|
||
enabled (bool):
|
||
Whether the stage is active.
|
||
'''
|
||
```
|
||
</code></pre></div></td></tr></table></div>
|
||
</details> <hr />
|
||
<h3 id="docforge--type-parity-pyi-stubs-and-pytyped">Type parity (<code>.pyi</code> stubs and <code>py.typed</code>)</h3>
|
||
<p>Documented APIs ship matching type information:</p>
|
||
<ul>
|
||
<li>Each <code>.py</code> module has a synchronized <code>.pyi</code> stub in the same package.</li>
|
||
<li>Packages expose a <code>py.typed</code> marker so type checkers (and consumers)
|
||
use the authored signatures instead of <code>Any</code>.</li>
|
||
<li>When signatures change, update the <code>.py</code> implementation and its <code>.pyi</code>
|
||
stub together.</li>
|
||
<li>Doc-forge documents the docstrings in <code>.py</code>; the <code>.pyi</code> stub is the
|
||
machine-consumable signature surface.</li>
|
||
</ul>
|
||
<hr />
|
||
<h3 id="docforge--parsing-guarantees">Parsing guarantees</h3>
|
||
<p>GSDFC ensures doc-forge can deterministically extract:</p>
|
||
<ul>
|
||
<li>symbol kind (module, class, function, property, attribute)</li>
|
||
<li>symbol name</li>
|
||
<li>parameters</li>
|
||
<li>return values</li>
|
||
<li>attributes</li>
|
||
<li>examples</li>
|
||
<li>structured Notes subsections</li>
|
||
</ul>
|
||
<p>This enables:</p>
|
||
<ul>
|
||
<li>reliable MkDocs rendering</li>
|
||
<li>deterministic MCP export</li>
|
||
<li>accurate AI semantic interpretation</li>
|
||
</ul>
|
||
<hr />
|
||
|
||
|
||
<details class="notes" open>
|
||
<summary>Notes</summary>
|
||
<ul>
|
||
<li>doc-forge never executes analyzed modules.</li>
|
||
<li>Documentation is generated entirely through static analysis.</li>
|
||
</ul>
|
||
</details>
|
||
|
||
|
||
<div class="doc doc-children">
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<h3 id="docforge-classes">Classes</h3>
|
||
|
||
<div class="doc doc-object doc-class">
|
||
|
||
|
||
|
||
<h4 id="docforge.GriffeLoader" class="doc doc-heading">
|
||
<code class="doc-symbol doc-symbol-heading doc-symbol-class"></code> <span class="doc doc-object-name doc-class-name">GriffeLoader</span>
|
||
|
||
|
||
</h4>
|
||
<div class="language-python doc-signature highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span><span class="normal"><a href="#__codelineno-0-1">1</a></span></pre></div></td><td class="code"><div><pre><span></span><code><span id="__span-0-1"><a id="__codelineno-0-1" name="__codelineno-0-1"></a><span class="nf">GriffeLoader</span><span class="p">()</span>
|
||
</span></code></pre></div></td></tr></table></div>
|
||
|
||
<div class="doc doc-contents ">
|
||
|
||
|
||
<p>Load Python modules using Griffe and convert them into doc-forge models.</p>
|
||
<p>This loader uses the Griffe introspection engine to analyze Python source
|
||
code and transform the extracted information into <code>Project</code>, <code>Module</code>,
|
||
and <code>DocObject</code> instances used by doc-forge.</p>
|
||
|
||
|
||
<p><span class="doc-section-title">Attributes:</span></p>
|
||
<table>
|
||
<thead>
|
||
<tr>
|
||
<th>Name</th>
|
||
<th>Type</th>
|
||
<th>Description</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr class="doc-section-item">
|
||
<td><code><span title="docforge.GriffeLoader._loader">_loader</span></code></td>
|
||
<td>
|
||
<code><span title="griffe.GriffeLoader">GriffeLoader</span></code>
|
||
</td>
|
||
<td>
|
||
<div class="doc-md-description">
|
||
<p>Internal Griffe loader with dedicated module and line collections.</p>
|
||
</div>
|
||
</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
|
||
<p>Initialize the Griffe-backed loader.</p>
|
||
<p>Creates an internal Griffe loader instance with dedicated collections
|
||
for modules and source lines.</p>
|
||
|
||
|
||
|
||
|
||
<div class="doc doc-children">
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<h5 id="docforge.GriffeLoader-functions">Functions</h5>
|
||
|
||
<div class="doc doc-object doc-function">
|
||
|
||
|
||
<h6 id="docforge.GriffeLoader.load_module" class="doc doc-heading">
|
||
<code class="doc-symbol doc-symbol-heading doc-symbol-method"></code> <span class="doc doc-object-name doc-function-name">load_module</span>
|
||
|
||
|
||
</h6>
|
||
<div class="language-python doc-signature highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span><span class="normal"><a href="#__codelineno-0-1">1</a></span></pre></div></td><td class="code"><div><pre><span></span><code><span id="__span-0-1"><a id="__codelineno-0-1" name="__codelineno-0-1"></a><span class="nf">load_module</span><span class="p">(</span><span class="n">path</span><span class="p">:</span> <span class="nb">str</span><span class="p">)</span> <span class="o">-></span> <span class="n">Module</span>
|
||
</span></code></pre></div></td></tr></table></div>
|
||
|
||
<div class="doc doc-contents ">
|
||
|
||
<p>Load and convert a single Python module.</p>
|
||
<p>The module is introspected using Griffe and then transformed into
|
||
a doc-forge <code>Module</code> model.</p>
|
||
|
||
|
||
<p><span class="doc-section-title">Parameters:</span></p>
|
||
<table>
|
||
<thead>
|
||
<tr>
|
||
<th>Name</th>
|
||
<th>Type</th>
|
||
<th>Description</th>
|
||
<th>Default</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr class="doc-section-item">
|
||
<td><code>path</code></td>
|
||
<td>
|
||
<code>str</code>
|
||
</td>
|
||
<td>
|
||
<div class="doc-md-description">
|
||
<p>Dotted import path of the module.</p>
|
||
</div>
|
||
</td>
|
||
<td>
|
||
<em>required</em>
|
||
</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
|
||
|
||
<p><span class="doc-section-title">Returns:</span></p>
|
||
<table>
|
||
<thead>
|
||
<tr>
|
||
<th>Name</th> <th>Type</th>
|
||
<th>Description</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr class="doc-section-item">
|
||
<td><code>Module</code></td> <td>
|
||
<code><a class="autorefs autorefs-internal" title="docforge.models.Module" href="models/#docforge.models.Module">Module</a></code>
|
||
</td>
|
||
<td>
|
||
<div class="doc-md-description">
|
||
<p>A populated <code>Module</code> instance.</p>
|
||
</div>
|
||
</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
|
||
|
||
<p><span class="doc-section-title">Raises:</span></p>
|
||
<table>
|
||
<thead>
|
||
<tr>
|
||
<th>Type</th>
|
||
<th>Description</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr class="doc-section-item">
|
||
<td>
|
||
<code>ImportError</code>
|
||
</td>
|
||
<td>
|
||
<div class="doc-md-description">
|
||
<p>If the module cannot be loaded by Griffe.</p>
|
||
</div>
|
||
</td>
|
||
</tr>
|
||
<tr class="doc-section-item">
|
||
<td>
|
||
<code>KeyError</code>
|
||
</td>
|
||
<td>
|
||
<div class="doc-md-description">
|
||
<p>If the loaded module is missing from the module collection.</p>
|
||
</div>
|
||
</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
|
||
|
||
<details class="example" open>
|
||
<summary>Example</summary>
|
||
<p>Load a single module:</p>
|
||
<div class="language-text highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span><span class="normal">1</span>
|
||
<span class="normal">2</span>
|
||
<span class="normal">3</span>
|
||
<span class="normal">4</span></pre></div></td><td class="code"><div><pre><span></span><code>```python
|
||
loader = GriffeLoader()
|
||
module = loader.load_module("mypackage.submodule")
|
||
```
|
||
</code></pre></div></td></tr></table></div>
|
||
</details>
|
||
</div>
|
||
|
||
</div>
|
||
|
||
<div class="doc doc-object doc-function">
|
||
|
||
|
||
<h6 id="docforge.GriffeLoader.load_project" class="doc doc-heading">
|
||
<code class="doc-symbol doc-symbol-heading doc-symbol-method"></code> <span class="doc doc-object-name doc-function-name">load_project</span>
|
||
|
||
|
||
</h6>
|
||
<div class="language-python doc-signature highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span><span class="normal"><a href="#__codelineno-0-1">1</a></span>
|
||
<span class="normal"><a href="#__codelineno-0-2">2</a></span>
|
||
<span class="normal"><a href="#__codelineno-0-3">3</a></span>
|
||
<span class="normal"><a href="#__codelineno-0-4">4</a></span>
|
||
<span class="normal"><a href="#__codelineno-0-5">5</a></span></pre></div></td><td class="code"><div><pre><span></span><code><span id="__span-0-1"><a id="__codelineno-0-1" name="__codelineno-0-1"></a><span class="nf">load_project</span><span class="p">(</span>
|
||
</span><span id="__span-0-2"><a id="__codelineno-0-2" name="__codelineno-0-2"></a> <span class="n">module_paths</span><span class="p">:</span> <span class="nb">list</span><span class="p">[</span><span class="nb">str</span><span class="p">],</span>
|
||
</span><span id="__span-0-3"><a id="__codelineno-0-3" name="__codelineno-0-3"></a> <span class="n">project_name</span><span class="p">:</span> <span class="nb">str</span> <span class="o">|</span> <span class="kc">None</span> <span class="o">=</span> <span class="kc">None</span><span class="p">,</span>
|
||
</span><span id="__span-0-4"><a id="__codelineno-0-4" name="__codelineno-0-4"></a> <span class="n">skip_import_errors</span><span class="p">:</span> <span class="nb">bool</span> <span class="o">|</span> <span class="kc">None</span> <span class="o">=</span> <span class="kc">None</span><span class="p">,</span>
|
||
</span><span id="__span-0-5"><a id="__codelineno-0-5" name="__codelineno-0-5"></a><span class="p">)</span> <span class="o">-></span> <span class="n">Project</span>
|
||
</span></code></pre></div></td></tr></table></div>
|
||
|
||
<div class="doc doc-contents ">
|
||
|
||
<p>Load multiple modules and assemble them into a Project model.</p>
|
||
<p>Each module path is introspected and converted into a <code>Module</code>
|
||
instance. All modules are then aggregated into a single <code>Project</code>
|
||
object.</p>
|
||
|
||
|
||
<p><span class="doc-section-title">Parameters:</span></p>
|
||
<table>
|
||
<thead>
|
||
<tr>
|
||
<th>Name</th>
|
||
<th>Type</th>
|
||
<th>Description</th>
|
||
<th>Default</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr class="doc-section-item">
|
||
<td><code>module_paths</code></td>
|
||
<td>
|
||
<code>list[str]</code>
|
||
</td>
|
||
<td>
|
||
<div class="doc-md-description">
|
||
<p>List of dotted module import paths to load.</p>
|
||
</div>
|
||
</td>
|
||
<td>
|
||
<em>required</em>
|
||
</td>
|
||
</tr>
|
||
<tr class="doc-section-item">
|
||
<td><code>project_name</code></td>
|
||
<td>
|
||
<code>str | None</code>
|
||
</td>
|
||
<td>
|
||
<div class="doc-md-description">
|
||
<p>Optional override for the project name. Defaults to the top-level
|
||
name of the first module.</p>
|
||
</div>
|
||
</td>
|
||
<td>
|
||
<code>None</code>
|
||
</td>
|
||
</tr>
|
||
<tr class="doc-section-item">
|
||
<td><code>skip_import_errors</code></td>
|
||
<td>
|
||
<code>bool | None</code>
|
||
</td>
|
||
<td>
|
||
<div class="doc-md-description">
|
||
<p>If True, modules that fail to load will be skipped instead of raising an error.</p>
|
||
</div>
|
||
</td>
|
||
<td>
|
||
<code>None</code>
|
||
</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
|
||
|
||
<p><span class="doc-section-title">Returns:</span></p>
|
||
<table>
|
||
<thead>
|
||
<tr>
|
||
<th>Name</th> <th>Type</th>
|
||
<th>Description</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr class="doc-section-item">
|
||
<td><code>Project</code></td> <td>
|
||
<code><a class="autorefs autorefs-internal" title="docforge.models.Project" href="models/#docforge.models.Project">Project</a></code>
|
||
</td>
|
||
<td>
|
||
<div class="doc-md-description">
|
||
<p>A populated <code>Project</code> instance containing the loaded modules.</p>
|
||
</div>
|
||
</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
|
||
|
||
<p><span class="doc-section-title">Raises:</span></p>
|
||
<table>
|
||
<thead>
|
||
<tr>
|
||
<th>Type</th>
|
||
<th>Description</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr class="doc-section-item">
|
||
<td>
|
||
<code>ValueError</code>
|
||
</td>
|
||
<td>
|
||
<div class="doc-md-description">
|
||
<p>If no module paths are provided.</p>
|
||
</div>
|
||
</td>
|
||
</tr>
|
||
<tr class="doc-section-item">
|
||
<td>
|
||
<code>ImportError</code>
|
||
</td>
|
||
<td>
|
||
<div class="doc-md-description">
|
||
<p>If a module fails to load and <code>skip_import_errors</code> is False.</p>
|
||
</div>
|
||
</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
|
||
</div>
|
||
|
||
</div>
|
||
|
||
|
||
|
||
</div>
|
||
|
||
</div>
|
||
|
||
</div>
|
||
|
||
<div class="doc doc-object doc-class">
|
||
|
||
|
||
|
||
<h4 id="docforge.MCPRenderer" class="doc doc-heading">
|
||
<code class="doc-symbol doc-symbol-heading doc-symbol-class"></code> <span class="doc doc-object-name doc-class-name">MCPRenderer</span>
|
||
|
||
|
||
</h4>
|
||
|
||
|
||
<div class="doc doc-contents ">
|
||
|
||
|
||
<p>Renderer that generates MCP-compatible documentation resources.</p>
|
||
<p>This renderer converts doc-forge project models into structured JSON
|
||
resources suitable for consumption by systems implementing the Model
|
||
Context Protocol (MCP).</p>
|
||
|
||
|
||
|
||
|
||
<div class="doc doc-children">
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<h5 id="docforge.MCPRenderer-functions">Functions</h5>
|
||
|
||
<div class="doc doc-object doc-function">
|
||
|
||
|
||
<h6 id="docforge.MCPRenderer.generate_sources" class="doc doc-heading">
|
||
<code class="doc-symbol doc-symbol-heading doc-symbol-method"></code> <span class="doc doc-object-name doc-function-name">generate_sources</span>
|
||
|
||
|
||
</h6>
|
||
<div class="language-python doc-signature highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span><span class="normal"><a href="#__codelineno-0-1">1</a></span></pre></div></td><td class="code"><div><pre><span></span><code><span id="__span-0-1"><a id="__codelineno-0-1" name="__codelineno-0-1"></a><span class="nf">generate_sources</span><span class="p">(</span><span class="n">project</span><span class="p">:</span> <span class="n">Project</span><span class="p">,</span> <span class="n">out_dir</span><span class="p">:</span> <span class="n">Path</span><span class="p">)</span> <span class="o">-></span> <span class="kc">None</span>
|
||
</span></code></pre></div></td></tr></table></div>
|
||
|
||
<div class="doc doc-contents ">
|
||
|
||
<p>Generate MCP documentation resources for a project.</p>
|
||
<p>The renderer serializes each module into a JSON resource and produces
|
||
supporting metadata files such as <code>nav.json</code> and <code>index.json</code>.</p>
|
||
|
||
|
||
<p><span class="doc-section-title">Parameters:</span></p>
|
||
<table>
|
||
<thead>
|
||
<tr>
|
||
<th>Name</th>
|
||
<th>Type</th>
|
||
<th>Description</th>
|
||
<th>Default</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr class="doc-section-item">
|
||
<td><code>project</code></td>
|
||
<td>
|
||
<code><a class="autorefs autorefs-internal" title="docforge.models.Project" href="models/#docforge.models.Project">Project</a></code>
|
||
</td>
|
||
<td>
|
||
<div class="doc-md-description">
|
||
<p>Documentation project model to render.</p>
|
||
</div>
|
||
</td>
|
||
<td>
|
||
<em>required</em>
|
||
</td>
|
||
</tr>
|
||
<tr class="doc-section-item">
|
||
<td><code>out_dir</code></td>
|
||
<td>
|
||
<code><span title="pathlib.Path">Path</span></code>
|
||
</td>
|
||
<td>
|
||
<div class="doc-md-description">
|
||
<p>Directory where MCP resources will be written.</p>
|
||
</div>
|
||
</td>
|
||
<td>
|
||
<em>required</em>
|
||
</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
|
||
</div>
|
||
|
||
</div>
|
||
|
||
|
||
|
||
</div>
|
||
|
||
</div>
|
||
|
||
</div>
|
||
|
||
<div class="doc doc-object doc-class">
|
||
|
||
|
||
|
||
<h4 id="docforge.MkDocsRenderer" class="doc doc-heading">
|
||
<code class="doc-symbol doc-symbol-heading doc-symbol-class"></code> <span class="doc doc-object-name doc-class-name">MkDocsRenderer</span>
|
||
|
||
|
||
</h4>
|
||
|
||
|
||
<div class="doc doc-contents ">
|
||
|
||
|
||
<p>Renderer that produces Markdown documentation for MkDocs.</p>
|
||
<p>Generated pages use mkdocstrings directives to reference Python modules,
|
||
allowing MkDocs to render API documentation dynamically.</p>
|
||
|
||
|
||
|
||
|
||
<div class="doc doc-children">
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<h5 id="docforge.MkDocsRenderer-functions">Functions</h5>
|
||
|
||
<div class="doc doc-object doc-function">
|
||
|
||
|
||
<h6 id="docforge.MkDocsRenderer.generate_readme" class="doc doc-heading">
|
||
<code class="doc-symbol doc-symbol-heading doc-symbol-method"></code> <span class="doc doc-object-name doc-function-name">generate_readme</span>
|
||
|
||
|
||
</h6>
|
||
<div class="language-python doc-signature highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span><span class="normal"><a href="#__codelineno-0-1">1</a></span>
|
||
<span class="normal"><a href="#__codelineno-0-2">2</a></span>
|
||
<span class="normal"><a href="#__codelineno-0-3">3</a></span>
|
||
<span class="normal"><a href="#__codelineno-0-4">4</a></span>
|
||
<span class="normal"><a href="#__codelineno-0-5">5</a></span>
|
||
<span class="normal"><a href="#__codelineno-0-6">6</a></span></pre></div></td><td class="code"><div><pre><span></span><code><span id="__span-0-1"><a id="__codelineno-0-1" name="__codelineno-0-1"></a><span class="nf">generate_readme</span><span class="p">(</span>
|
||
</span><span id="__span-0-2"><a id="__codelineno-0-2" name="__codelineno-0-2"></a> <span class="n">project</span><span class="p">:</span> <span class="n">Project</span><span class="p">,</span>
|
||
</span><span id="__span-0-3"><a id="__codelineno-0-3" name="__codelineno-0-3"></a> <span class="n">docs_dir</span><span class="p">:</span> <span class="n">Path</span><span class="p">,</span>
|
||
</span><span id="__span-0-4"><a id="__codelineno-0-4" name="__codelineno-0-4"></a> <span class="n">module_is_source</span><span class="p">:</span> <span class="nb">bool</span> <span class="o">|</span> <span class="kc">None</span> <span class="o">=</span> <span class="kc">None</span><span class="p">,</span>
|
||
</span><span id="__span-0-5"><a id="__codelineno-0-5" name="__codelineno-0-5"></a> <span class="n">readme_dir</span><span class="p">:</span> <span class="n">Path</span> <span class="o">|</span> <span class="kc">None</span> <span class="o">=</span> <span class="kc">None</span><span class="p">,</span>
|
||
</span><span id="__span-0-6"><a id="__codelineno-0-6" name="__codelineno-0-6"></a><span class="p">)</span> <span class="o">-></span> <span class="kc">None</span>
|
||
</span></code></pre></div></td></tr></table></div>
|
||
|
||
<div class="doc doc-contents ">
|
||
|
||
<p>Generate a <code>README.md</code> file from the root module docstring.</p>
|
||
|
||
|
||
<details class="notes" open>
|
||
<summary>Notes</summary>
|
||
<ul>
|
||
<li>If <code>module_is_source</code> is True, <code>README.md</code> is written to the
|
||
project root directory.</li>
|
||
<li>If False, README generation is currently not implemented.</li>
|
||
</ul>
|
||
</details>
|
||
|
||
<p><span class="doc-section-title">Parameters:</span></p>
|
||
<table>
|
||
<thead>
|
||
<tr>
|
||
<th>Name</th>
|
||
<th>Type</th>
|
||
<th>Description</th>
|
||
<th>Default</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr class="doc-section-item">
|
||
<td><code>project</code></td>
|
||
<td>
|
||
<code><a class="autorefs autorefs-internal" title="docforge.models.Project" href="models/#docforge.models.Project">Project</a></code>
|
||
</td>
|
||
<td>
|
||
<div class="doc-md-description">
|
||
<p>Project model containing documentation metadata.</p>
|
||
</div>
|
||
</td>
|
||
<td>
|
||
<em>required</em>
|
||
</td>
|
||
</tr>
|
||
<tr class="doc-section-item">
|
||
<td><code>docs_dir</code></td>
|
||
<td>
|
||
<code><span title="pathlib.Path">Path</span></code>
|
||
</td>
|
||
<td>
|
||
<div class="doc-md-description">
|
||
<p>Directory containing generated documentation sources.</p>
|
||
</div>
|
||
</td>
|
||
<td>
|
||
<em>required</em>
|
||
</td>
|
||
</tr>
|
||
<tr class="doc-section-item">
|
||
<td><code>module_is_source</code></td>
|
||
<td>
|
||
<code>bool | None</code>
|
||
</td>
|
||
<td>
|
||
<div class="doc-md-description">
|
||
<p>Whether the module is treated as the project source root.</p>
|
||
</div>
|
||
</td>
|
||
<td>
|
||
<code>None</code>
|
||
</td>
|
||
</tr>
|
||
<tr class="doc-section-item">
|
||
<td><code>readme_dir</code></td>
|
||
<td>
|
||
<code><span title="pathlib.Path">Path</span> | None</code>
|
||
</td>
|
||
<td>
|
||
<div class="doc-md-description">
|
||
<p>Directory where the generated README.md should be written.
|
||
Defaults to the parent of <code>docs_dir</code>.</p>
|
||
</div>
|
||
</td>
|
||
<td>
|
||
<code>None</code>
|
||
</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
|
||
</div>
|
||
|
||
</div>
|
||
|
||
<div class="doc doc-object doc-function">
|
||
|
||
|
||
<h6 id="docforge.MkDocsRenderer.generate_sources" class="doc doc-heading">
|
||
<code class="doc-symbol doc-symbol-heading doc-symbol-method"></code> <span class="doc doc-object-name doc-function-name">generate_sources</span>
|
||
|
||
|
||
</h6>
|
||
<div class="language-python doc-signature highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span><span class="normal"><a href="#__codelineno-0-1">1</a></span>
|
||
<span class="normal"><a href="#__codelineno-0-2">2</a></span>
|
||
<span class="normal"><a href="#__codelineno-0-3">3</a></span>
|
||
<span class="normal"><a href="#__codelineno-0-4">4</a></span>
|
||
<span class="normal"><a href="#__codelineno-0-5">5</a></span></pre></div></td><td class="code"><div><pre><span></span><code><span id="__span-0-1"><a id="__codelineno-0-1" name="__codelineno-0-1"></a><span class="nf">generate_sources</span><span class="p">(</span>
|
||
</span><span id="__span-0-2"><a id="__codelineno-0-2" name="__codelineno-0-2"></a> <span class="n">project</span><span class="p">:</span> <span class="n">Project</span><span class="p">,</span>
|
||
</span><span id="__span-0-3"><a id="__codelineno-0-3" name="__codelineno-0-3"></a> <span class="n">out_dir</span><span class="p">:</span> <span class="n">Path</span><span class="p">,</span>
|
||
</span><span id="__span-0-4"><a id="__codelineno-0-4" name="__codelineno-0-4"></a> <span class="n">module_is_source</span><span class="p">:</span> <span class="nb">bool</span> <span class="o">|</span> <span class="kc">None</span> <span class="o">=</span> <span class="kc">None</span><span class="p">,</span>
|
||
</span><span id="__span-0-5"><a id="__codelineno-0-5" name="__codelineno-0-5"></a><span class="p">)</span> <span class="o">-></span> <span class="kc">None</span>
|
||
</span></code></pre></div></td></tr></table></div>
|
||
|
||
<div class="doc doc-contents ">
|
||
|
||
<p>Generate Markdown documentation files for a project.</p>
|
||
<p>This method renders a documentation structure from the provided
|
||
project model and writes the resulting Markdown files to the
|
||
specified output directory.</p>
|
||
|
||
|
||
<p><span class="doc-section-title">Parameters:</span></p>
|
||
<table>
|
||
<thead>
|
||
<tr>
|
||
<th>Name</th>
|
||
<th>Type</th>
|
||
<th>Description</th>
|
||
<th>Default</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr class="doc-section-item">
|
||
<td><code>project</code></td>
|
||
<td>
|
||
<code><a class="autorefs autorefs-internal" title="docforge.models.Project" href="models/#docforge.models.Project">Project</a></code>
|
||
</td>
|
||
<td>
|
||
<div class="doc-md-description">
|
||
<p>Project model containing modules to document.</p>
|
||
</div>
|
||
</td>
|
||
<td>
|
||
<em>required</em>
|
||
</td>
|
||
</tr>
|
||
<tr class="doc-section-item">
|
||
<td><code>out_dir</code></td>
|
||
<td>
|
||
<code><span title="pathlib.Path">Path</span></code>
|
||
</td>
|
||
<td>
|
||
<div class="doc-md-description">
|
||
<p>Directory where generated Markdown files will be written.</p>
|
||
</div>
|
||
</td>
|
||
<td>
|
||
<em>required</em>
|
||
</td>
|
||
</tr>
|
||
<tr class="doc-section-item">
|
||
<td><code>module_is_source</code></td>
|
||
<td>
|
||
<code>bool | None</code>
|
||
</td>
|
||
<td>
|
||
<div class="doc-md-description">
|
||
<p>If True, treat the specified module as the documentation root
|
||
rather than nesting it inside a folder.</p>
|
||
</div>
|
||
</td>
|
||
<td>
|
||
<code>None</code>
|
||
</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
|
||
</div>
|
||
|
||
</div>
|
||
|
||
|
||
|
||
</div>
|
||
|
||
</div>
|
||
|
||
</div>
|
||
<h3 id="docforge-functions">Functions</h3>
|
||
|
||
<div class="doc doc-object doc-function">
|
||
|
||
|
||
<h4 id="docforge.discover_module_paths" class="doc doc-heading">
|
||
<code class="doc-symbol doc-symbol-heading doc-symbol-function"></code> <span class="doc doc-object-name doc-function-name">discover_module_paths</span>
|
||
|
||
|
||
</h4>
|
||
<div class="language-python doc-signature highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span><span class="normal"><a href="#__codelineno-0-1">1</a></span>
|
||
<span class="normal"><a href="#__codelineno-0-2">2</a></span>
|
||
<span class="normal"><a href="#__codelineno-0-3">3</a></span></pre></div></td><td class="code"><div><pre><span></span><code><span id="__span-0-1"><a id="__codelineno-0-1" name="__codelineno-0-1"></a><span class="nf">discover_module_paths</span><span class="p">(</span>
|
||
</span><span id="__span-0-2"><a id="__codelineno-0-2" name="__codelineno-0-2"></a> <span class="n">module_name</span><span class="p">:</span> <span class="nb">str</span><span class="p">,</span> <span class="n">project_root</span><span class="p">:</span> <span class="n">Path</span> <span class="o">|</span> <span class="kc">None</span> <span class="o">=</span> <span class="kc">None</span>
|
||
</span><span id="__span-0-3"><a id="__codelineno-0-3" name="__codelineno-0-3"></a><span class="p">)</span> <span class="o">-></span> <span class="nb">list</span><span class="p">[</span><span class="nb">str</span><span class="p">]</span>
|
||
</span></code></pre></div></td></tr></table></div>
|
||
|
||
<div class="doc doc-contents ">
|
||
|
||
<p>Discover Python modules within a package directory.</p>
|
||
<p>The function scans the filesystem for <code>.py</code> files inside the specified
|
||
package and converts them into dotted module import paths.</p>
|
||
<p>Discovery rules:</p>
|
||
<ul>
|
||
<li>Directories containing <code>__init__.py</code> are treated as packages.</li>
|
||
<li>Each <code>.py</code> file is treated as a module.</li>
|
||
<li>Results are returned as dotted import paths.</li>
|
||
</ul>
|
||
|
||
|
||
<p><span class="doc-section-title">Parameters:</span></p>
|
||
<table>
|
||
<thead>
|
||
<tr>
|
||
<th>Name</th>
|
||
<th>Type</th>
|
||
<th>Description</th>
|
||
<th>Default</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr class="doc-section-item">
|
||
<td><code>module_name</code></td>
|
||
<td>
|
||
<code>str</code>
|
||
</td>
|
||
<td>
|
||
<div class="doc-md-description">
|
||
<p>Top-level package name to discover modules from.</p>
|
||
</div>
|
||
</td>
|
||
<td>
|
||
<em>required</em>
|
||
</td>
|
||
</tr>
|
||
<tr class="doc-section-item">
|
||
<td><code>project_root</code></td>
|
||
<td>
|
||
<code><span title="pathlib.Path">Path</span> | None</code>
|
||
</td>
|
||
<td>
|
||
<div class="doc-md-description">
|
||
<p>Root directory used to resolve module paths. If not provided, the
|
||
current working directory is used.</p>
|
||
</div>
|
||
</td>
|
||
<td>
|
||
<code>None</code>
|
||
</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
|
||
|
||
<p><span class="doc-section-title">Returns:</span></p>
|
||
<table>
|
||
<thead>
|
||
<tr>
|
||
<th>Type</th>
|
||
<th>Description</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr class="doc-section-item">
|
||
<td>
|
||
<code>list[str]</code>
|
||
</td>
|
||
<td>
|
||
<div class="doc-md-description">
|
||
<p>list[str]:
|
||
A sorted list of unique dotted module import paths.</p>
|
||
</div>
|
||
</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
|
||
|
||
<p><span class="doc-section-title">Raises:</span></p>
|
||
<table>
|
||
<thead>
|
||
<tr>
|
||
<th>Type</th>
|
||
<th>Description</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr class="doc-section-item">
|
||
<td>
|
||
<code>FileNotFoundError</code>
|
||
</td>
|
||
<td>
|
||
<div class="doc-md-description">
|
||
<p>If the specified package directory does not exist.</p>
|
||
</div>
|
||
</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
|
||
</div>
|
||
|
||
</div>
|
||
|
||
|
||
|
||
</div>
|
||
|
||
</div>
|
||
|
||
</div>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
</article>
|
||
</div>
|
||
|
||
|
||
<script>var tabs=__md_get("__tabs");if(Array.isArray(tabs))e:for(var set of document.querySelectorAll(".tabbed-set")){var labels=set.querySelector(".tabbed-labels");for(var tab of tabs)for(var label of labels.getElementsByTagName("label"))if(label.innerText.trim()===tab){var input=document.getElementById(label.htmlFor);input.checked=!0;continue e}}</script>
|
||
|
||
<script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script>
|
||
</div>
|
||
|
||
<button type="button" class="md-top md-icon" data-md-component="top" hidden>
|
||
|
||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg>
|
||
Back to top
|
||
</button>
|
||
|
||
</main>
|
||
|
||
<footer class="md-footer">
|
||
|
||
<div class="md-footer-meta md-typeset">
|
||
<div class="md-footer-meta__inner md-grid">
|
||
<div class="md-copyright">
|
||
|
||
|
||
Made with
|
||
<a href="https://squidfunk.github.io/mkdocs-material/" target="_blank" rel="noopener">
|
||
Material for MkDocs
|
||
</a>
|
||
|
||
</div>
|
||
|
||
</div>
|
||
</div>
|
||
</footer>
|
||
|
||
</div>
|
||
<div class="md-dialog" data-md-component="dialog">
|
||
<div class="md-dialog__inner md-typeset"></div>
|
||
</div>
|
||
|
||
|
||
|
||
|
||
<script id="__config" type="application/json">{"base": ".", "features": ["navigation.sections", "navigation.expand", "navigation.top", "navigation.instant", "navigation.tracking", "navigation.indexes", "content.code.copy", "content.code.annotate", "content.tabs.link", "content.action.edit", "search.highlight", "search.share", "search.suggest"], "search": "assets/javascripts/workers/search.973d3a69.min.js", "tags": null, "translations": {"clipboard.copied": "Copied to clipboard", "clipboard.copy": "Copy to clipboard", "search.result.more.one": "1 more on this page", "search.result.more.other": "# more on this page", "search.result.none": "No matching documents", "search.result.one": "1 matching document", "search.result.other": "# matching documents", "search.result.placeholder": "Type to start searching", "search.result.term.missing": "Missing", "select.version": "Select version"}, "version": null}</script>
|
||
|
||
|
||
<script src="assets/javascripts/bundle.f55a23d4.min.js"></script>
|
||
|
||
|
||
</body>
|
||
</html> |