Vishesh 'ironeagle' Bangotra
582b6809a0
- 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
42 lines
1.5 KiB
Markdown
42 lines
1.5 KiB
Markdown
# Conventions
|
|
|
|
## GSDFC docstrings
|
|
|
|
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`
|
|
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_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
|
|
directory.
|
|
- Navigation labels are derived by stripping the numeric prefix and applying
|
|
title case on the remaining words.
|
|
|
|
## Templates
|
|
|
|
MkDocs config fragments live in `docforge/templates`. The `mkdocs.wiki.yml`
|
|
fragment carries only the `search` plugin, since wiki pages contain no
|
|
mkdocstrings directives. |