Files

Vishesh 'ironeagle' Bangotra 4b0fdfaf85 docs(wiki): align wiki structure with Aetoskia AGENTS.md guidelines

- Renamed `02_architecture.md` to `02_components.md` to match the standard component page naming convention.
- Updated `docs/mkdocs.wiki.yml` to reflect renamed pages and fix navigation label acronym casing (GSDFC, MCP, MkDocs).
- Updated `index.md` to include the mandatory doc model blockquote, standardize section headers with emojis, and accurately map the `Documentation Structure` table to the navigation menu.
- Standardized all wiki pages (`01_overview.md`, `02_components.md`, `03_conventions.md`, `04_iterative_workflow.md`, and `05_development/*`) by:
  - Adding horizontal rules (`---`) between major sections.
  - Applying emoji-prefixed H2 headings for recognizable section types.
  - Appending `## Related` or `## ➡️ Read Next` footers with standard relative cross-links.
  - Adjusting H1 headers to match guide anatomy (e.g., `# Library Overview` on the overview page).

2026-09-14 23:30:45 +05:30

3.2 KiB

Raw Permalink Blame History

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:

Args:
Returns:
Raises:
Yields:
Notes:
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

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.

02 – Quality Gates · 04 – MCP Guide

3.2 KiB Raw Permalink Blame History Unescape Escape