Skip to content

📝 GSDFC Docstrings

khata-app adheres to the GSDFC docstring conventions (see the doc-forge GSDFC guide). The rules below are the ones enforced in this repo.

🏗 Core Rules

  • Modules — start with a Markdown # Summary heading, then a --- separator, then prose. Long modules follow with Notes:/Example: sections.
  • Classes — use Attributes: for fields, Notes: for invariants, Example: when a snippet clarifies usage.
  • Functions/methods — imperative summary line, then Args: / Returns: / Raises: / Yields: in that conventional order, then optional Notes: / Example:.
  • Prose types must match the signature verbatim — no modernization. If the source says str | None, the docstring and the stub say str | None; do not write Optional[str].

📄 Format Cheat-Sheet

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
"""# Summary

Imperative one-liner of what this does.

---

Args:
    name (str):
        Description on the next line.

Returns:
    bool:
        Description.
"""

A typical module docstring:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
"""# Summary

...one-liner...

---

Notes:
- point one.
- point two.
"""

🗃 Stub Files

Every module gets a sibling .pyi stub mirroring the public surface only:

  • exact signatures and return annotations,
  • ... bodies,
  • no docstrings (the source carries them),
  • no private helpers, no imports of implementation-only symbols.

Generate/validate conveniently with doc-forge's stub tooling, and always run py_compile + ruff on new stubs.

❌ Anti-Patterns

  • Docstrings that contradict annotations (typed vs untyped mismatch).
  • Forward-refs as strings in stubs (use a real import instead — e.g. from dagpipe import Pipeline).
  • Documenting private / underscored members in stubs (public surface only).

Building Docs · Testing · Development