aetos/doc-forge
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
582b6809a07090d26a019f570a3e3fd5ecc99063
doc-forge/docs/wiki/03_conventions.md
Vishesh 'ironeagle' Bangotra 582b6809a0 docs: bring docforge docstrings and wiki to GSDFC standard 
- 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
2026-09-12 13:12:51 +05:30

1.5 KiB
Raw Blame History

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.