aetos/doc-forge
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: bring docforge docstrings and wiki to GSDFC standard

Browse Source 
- fix GSDFC spec contradictions in __init__ docstring (parenthesized types, fenced-block rule) and sync generated README
- rewrite docstrings across loaders, models, nav, servers, renderers, cli; sync .pyi stubs
- add pydoclint (google style) gate to dev extras and pyproject config
- fix mcp nav resources doc:// -> docs://
- refresh docs/lib and docs/mcp, drop stale docforge/ duplicate group
- update wiki pages and add GSDFC + MCP guides under 05_development
This commit is contained in:
Vishesh 'ironeagle' Bangotra
2026-09-12 13:12:51 +05:30
parent 8c6c46caf2
commit 582b6809a0
82 changed files with 1467 additions and 703 deletions
Download Patch File Download Diff File Expand all files Collapse all files

10
docs/wiki/01_overview.md
View File

@@ -11,7 +11,7 @@ and assembles a single MkDocs site from all available material.
| `lib` | GSDFC docstrings | `docs/lib/**` rendered markdown |
| `api` | OpenAPI JSON spec | `docs/api/**` rendered markdown |
| `wiki` | Hand-written markdown | `docs/wiki/**` (unchanged) |
| `mcp` | Griffe + renderers | `docs/mcp/**` structured files |
| `mcp` | GSDFC docstrings + renderers | `docs/mcp/**` structured JSON |
## Combined build
@@ -22,4 +22,10 @@ One `mkdocs.yml` and one MkDocs build serve all kinds:
3. The wiki `index.md` becomes the site `Home`.
Hand-written wiki content is never overwritten or regenerated — only its
navigation is derived automatically.
navigation is derived automatically.
## MCP bundle
`docs/mcp/**` is a self-contained, machine-readable reference generated from
docforge's own GSDFC docstrings. `doc-forge serve --mcp --module docforge`
serves it over MCP. See the [MCP Guide](05_development/04_mcp_guide.md).

10
docs/wiki/02_architecture.md
View File

@@ -7,8 +7,7 @@ bottom through the CLI.
The `docforge/loaders` package wraps `griffe` to extract modules, functions,
classes, and Google-style docstring sections. Loaded data is normalized into
the object model under `docforge/models` (`Module`, `Object`, `Project`,
`Field`).
the object model under `docforge/models` (`Project`, `Module`, `DocObject`).
## Navigation
@@ -23,6 +22,13 @@ file structure via `build_wiki_nav`.
- `MkDocsRenderer` → `docs/lib/**` reference markdown
- `MCPRenderer` → `docs/mcp/**` structured documentation
## Servers
`docforge/servers` serves generated artifacts over live protocols:
- `MCPServer` → serves a pre-generated `docs/mcp/**` bundle through MCP
resources (`docs://index`, `docs://nav`, `docs://modules/{module}`)
## CLI
`docforge/cli` wires it all together:

15
docs/wiki/03_conventions.md
View File

@@ -6,6 +6,19 @@ All documented source uses the Google-Styled Doc-Forge Convention (GSDFC):
`Args:`, `Returns:`, `Raises:`, and `Attributes:` sections with properly typed
signatures.
The authoritative GSDFC specification lives in the `docforge/__init__.py`
package docstring, which is exported verbatim into
`docs/mcp/modules/docforge.json`, so the MCP bundle is self-documenting.
Key rules:
- Use parenthesized types in prose entries (`name (Type):`) that match the
signature types.
- Use `# Summary`, `# Examples`, and `# Notes` sections at module level.
- Use `Args:`, `Returns:`, `Raises:`, `Yields:`, `Notes:`, and `Example:`
sections at function and method level.
- Always update the matching `.pyi` stub alongside the `.py` implementation.
## `.pyi` stubs
Every module ships a matching `.pyi` stub kept in sync with the `.py`
@@ -14,7 +27,7 @@ implementation. When signatures change, update both files.
## Wiki pages
- Hand-written markdown lives in `docs/wiki/**` and is never generated.
- File names use a numeric prefix: `01_overview.md`, `02_components.md`.
- File names use a numeric prefix: `01_overview.md`, `02_architecture.md`.
- Nested directories become nested navigation groups:
`05_development/01_environment.md` → group *Development*.
- `index.md` is the site `Home` at the root, and a section root inside a

14
docs/wiki/04_iterative_workflow.md
View File

@@ -8,11 +8,14 @@ A docs build runs through the CLI in a single pass.
# Library reference only
doc-forge build --mkdocs --module docforge
# Wik + library combined (single MkDocs build)
# Wiki + library combined (single MkDocs build)
doc-forge build --wiki --mkdocs --module docforge
# Wiki only — no module required
doc-forge build --wiki --site-name docforge
# MCP structured bundle
doc-forge build --mcp --module docforge
```
## What a combined build does
@@ -29,5 +32,12 @@ doc-forge build --wiki --site-name docforge
```bash
doc-forge build --wiki --mkdocs --module docforge
doc-forge serve --mkdocs-yml mkdocs.yml
doc-forge serve --mkdocs --mkdocs-yml mkdocs.yml
```
## Serve the MCP bundle
```bash
doc-forge build --mcp --module docforge
doc-forge serve --mcp --module docforge
```

5
docs/wiki/05_development/01_environment.md
View File

@@ -8,7 +8,7 @@ python -m venv .venv
pip install -e .
```
Requires Python 3.11+.
Requires Python 3.10+ (per `pyproject.toml`).
## Dependencies
@@ -17,4 +17,5 @@ Development extras include:
- `pytest`, `pytest-cov` — test suite and coverage
- `ruff` — lint and format checking
- `black` — auto-formatting
- `mypy` — strict typing checks
- `mypy` — strict typing checks
- `pydoclint` — docstring ↔ signature consistency checks

1
docs/wiki/05_development/02_quality_gates.md
View File

@@ -7,6 +7,7 @@ Run all checks before pushing:
.venv\Scripts\python.exe -m ruff check docforge tests
.venv\Scripts\python.exe -m black --check docforge tests
.venv\Scripts\python.exe -m mypy docforge
.venv\Scripts\pydoclint.exe docforge
```
## Test layout

108
docs/wiki/05_development/03_gsdfc_guide.md Normal file
View File

@@ -0,0 +1,108 @@
# GSDFC Docstring Guide
This page is the practical companion to the authoritative GSDFC specification
in the `docforge/__init__.py` package docstring. It describes how to write
docstrings that render correctly in MkDocs and stay machine-parseable by
doc-forge, MkDocs, and MCP clients.
## Overview
- Docstrings are the single source of truth.
- `doc-forge` compiles docstrings but never rewrites them.
- Every public symbol should have a complete, accurate docstring.
- Type hints live in signatures; prose entries repeat the type in
parentheses and must match the signature.
## Module docstrings
Modules use Markdown headings and `---` separators.
Recommended sections:
- `# Summary` — what the subsystem does
- `# Examples` — a representative usage snippet
- `# Notes` — guarantees, lifecycle, and thread-safety notes
## Class docstrings
Recommended sections, in order:
- summary line describing responsibility
- `Attributes:` — instance attributes with `name (Type):` entries
- `Notes:` — grouped subsections such as **Guarantees**, **Lifecycle**
- `Example:` — indented `python` code block
## Function and method docstrings
Recommended section order:
1. `Args:`
2. `Returns:`
3. `Raises:`
4. `Yields:`
5. `Notes:`
6. `Example:`
Formatting rules:
- `Args:` entries are `name (Type):` followed by an indented description.
- `Returns:` entries are `Type:` followed by an indented description.
- `Raises:` entries are `ExceptionType:` followed by an indented condition.
- `Yields:` replaces `Returns:` for generators.
- Summaries are written in the imperative mood.
- Fenced `python` blocks are allowed inside `Example:` sections, indented
four spaces.
## Property docstrings
Properties document their return values with a `Returns:` section and, when
meaningful, an `Example:`.
## Example
```python
def 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.
Example:
Process foo:
```python
foo = Foo("example", value=10)
result = process(foo, multiplier=2)
print(result)
```
"""
```
## Keeping stubs in sync
Every `.py` module ships a matching `.pyi` stub. When a signature or a public
symbol changes, update both files. Signature annotations in the stub must
match the implementation.
## Enforcement
`pydoclint` (Google style) runs in CI and verifies that `Args:`/`Returns:`
sections match function signatures, including types.
- `allow-init-docstring = true` — `__init__` docstrings are allowed.
- `skip-checking-raises = true` — `Raises:` sections are descriptive and are
not required to map to literal `raise` statements.
- `check-class-attributes = false` — `Attributes:` sections document instance
attributes without class-level annotations.

51
docs/wiki/05_development/04_mcp_guide.md Normal file
View File

@@ -0,0 +1,51 @@
# MCP Guide
Doc-forge can export a machine-readable **MCP bundle** from a project's
GSDFC docstrings and serve that bundle over the Model Context Protocol (MCP).
The bundle is self-contained: readers can derive the full API reference —
signatures, docstrings, and structure — for the documented project.
## Building the bundle
```bash
doc-forge build --mcp --module docforge
```
This writes structured JSON into `docs/mcp/`:
- `index.json` — project metadata and module count
- `nav.json` — module list with `docs://modules/{module}` resource URIs
- `modules/{dotted.path}.json` — per-module serialized documentation
## Serving the bundle
```bash
doc-forge serve --mcp --module docforge
```
The `MCPServer` (in `docforge/servers/mcp_server.py`) exposes:
| Resource | Description |
|----------------------|-----------------------------------|
| `docs://index` | Project metadata |
| `docs://nav` | Navigation structure |
| `docs://modules/{module}` | Individual module documentation |
The server also registers a single diagnostic tool, `ping`, and is read-only.
Missing resources are returned as structured error dictionaries rather than
exceptions. The default transport is `streamable-http`; `stdio` and `sse` are
supported via `MCPServer.run`.
## Bundle contents
Each module resource contains:
- `path` — dotted module path
- `docstring` — the raw GSDFC module docstring
- `objects` — a recursive mapping of public symbols with `name`, `kind`,
`path`, `signature`, and `docstring`, plus nested `members`
Because the bundle is generated from docstrings, the quality of the bundle
equals the quality of the project's GSDFC docstrings. For docforge itself,
the GSDFC specification is carried in `modules/docforge.json` via the
`docforge/__init__.py` package docstring, making the bundle self-documenting.

7
docs/wiki/index.md
View File

@@ -22,17 +22,20 @@ OpenAPI-based API docs.
| Section | Description |
|----------------------------------------------| -------------------------------------------------- |
| [Overview](01_overview.md) | What docforge is and how it fits the pipeline |
| [Architecture](02_architecture.md) | Loaders, models, nav, renderers, CLI |
| [Architecture](02_architecture.md) | Loaders, models, nav, renderers, CLI, servers |
| [Conventions](03_conventions.md) | GSDFC, `.pyi` stubs, and template conventions |
| [Iterative Workflow](04_iterative_workflow.md) | How a docs build runs end to end |
| [Development](05_development/01_environment.md) | Environment setup and quality gates |
| [Docstring Guide](05_development/03_gsdfc_guide.md) | How to write GSDFC-conformant docstrings |
| [MCP Guide](05_development/04_mcp_guide.md) | Building, serving, and consuming the MCP bundle |
---
## 🔗 Related Resources
- **Source Code:** `C:\Users\vishe\WorkSpace\code\aetos\doc-forge`
- **Source Code:** the `doc-forge` repository
- **Wiki Kind:** hand-written content lives in `docs/wiki/`
- **MCP Bundle:** generated by `doc-forge build --mcp --module docforge` into `docs/mcp/`
---