aetos/doc-forge
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
lib-standardisation
doc-forge/docs/wiki/03_conventions.md

1.9 KiB
Raw Permalink 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:

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

.pyi stubs and py.typed

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

Wiki pages

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

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.

Related