Revise Docstrings

Revise Docstrings

Skill for reviewing and improving Python docstrings so they render correctly and completely in a Great Docs API reference site.

Quick start

# Preview what Great Docs will document
great-docs scan --verbose

# Build and check the rendered reference
great-docs build && great-docs preview

Skill directory structure

skills/revise-docstrings/
├── SKILL.md
└── references/
    ├── docstring-checklist.md
    └── style-examples.md

When to use this skill

Core concepts

Docstring formats

Great Docs supports two formats. Set the parser in config:

# great-docs.yml
parser: numpy # or "google"

Both produce identical rendered output. Use whichever your codebase already uses.

NumPy style

def connect(host: str, port: int = 5432) -> Connection:
    """
    Open a connection to the database server.

    Establishes a TCP connection to the specified host and port, authenticates
    with default credentials, and returns an active connection handle.

    Parameters
    ----------
    host
        Hostname or IP address of the database server.
    port
        TCP port number. Defaults to `5432`.

    Returns
    -------
    Connection
        An authenticated connection ready for queries.

    Raises
    ------
    ConnectionError
        If the server is unreachable.

    Examples
    --------
    Connect to a local server and run a simple query:

    ```{python}
    conn = connect("localhost")
    conn.execute("SELECT 1")
    ```

    See Also
    --------
    disconnect : Close a connection.

    Notes
    -----
    The connection uses TLS by default when port 5433 is specified.
    """

Google style

def connect(host: str, port: int = 5432) -> Connection:
    """Open a connection to the database server.

    Establishes a TCP connection to the specified host and port, authenticates
    with default credentials, and returns an active connection handle.

    Args:
        host: Hostname or IP address of the database server.
        port: TCP port number. Defaults to `5432`.

    Returns:
        An authenticated connection ready for queries.

    Raises:
        ConnectionError: If the server is unreachable.

    Examples:
        Connect and run a query:

        ```{python}
        conn = connect("localhost")
        conn.execute("SELECT 1")
        ```
    """

Sections recognized by Great Docs

Great Docs directives

Special inline directives using % prefix:

def my_function():
    """
    Description.

    %seealso other_func, SomeClass: related utilities
    %nodoc
    """

Type annotations vs docstring types

• Prefer type annotations in the function signature.
• Great Docs reads annotations automatically — no need to duplicate types in the docstring. Write bare parameter names (e.g., host not host : str) and let the signature annotation render on the reference page.
• If you do add a type in the docstring (e.g., host : str), it overwrites the annotation in the rendered output. This can be useful to show a simplified form (e.g., str or Path instead of str | pathlib.Path), but it creates a maintenance risk: the docstring type and the annotation can drift apart silently.
• Rule of thumb: omit docstring types unless the annotation is confusing to readers. Keep one source of truth.

Workflows

Auditing a package's docstrings

Task Progress:
- [ ] Step 1: List public API
- [ ] Step 2: Check each symbol
- [ ] Step 3: Fix issues
- [ ] Step 4: Rebuild and verify

Step 1: Run great-docs scan --verbose to see every symbol Great Docs will document.

Step 2: For each symbol, run through the checklist in references/docstring-checklist.md.

Step 3: Fix missing or incorrect sections. Use references/style-examples.md as a template.

Step 4: Rebuild with great-docs build and check the rendered pages in the browser.

Writing a docstring from scratch

1. Start with a one-line summary (imperative mood: "Connect to...", "Return the...", "Parse the...").
2. Add an extended summary if the one-liner is insufficient.
3. Document every parameter with name, type, and description.
4. Document the return value.
5. Add Raises if the function can raise exceptions.
6. Add an Examples section with Quarto code cells (preferred) or >>> prompts. Use {python} for executable cells, {.python} for display-only. Wrap cells with short prose.
7. Add %seealso for closely related symbols.

Fixing a rendering issue

Common rendering problems and their fixes:

Gotchas

1. One-line summary is required. Without it, the API reference page shows no description at all.
2. Blank line after summary. NumPy style requires a blank line between the summary and the extended summary.
3. Indentation matters. Parameters must be indented consistently (4 spaces for NumPy, nested under Args: for Google).
4. Don't mix styles. All docstrings in a package must use the same format. Mixing causes parsing failures.
5. %nodoc hides completely. Use exclude in config for selective hiding without modifying source code.
6. Prefer Quarto cells over >>> prompts. {python} cells render output automatically and support prose between steps. Use {.python} for non-executable illustration.
7. Class docstrings go on the class, not __init__. Great Docs reads the class-level docstring for the class page.