Cross-Reference Related Items

Link related classes, functions, and methods using the Great Docs Linking System (GDLS).

The Great Docs Linking System (GDLS) creates clickable links between API items. Use whichever style fits your docstrings.

`%seealso` Directive

Add %seealso to a docstring with a comma-separated list of names:

def encode(data: bytes, encoding: str = "utf-8") -> str:
    """Encode bytes to a string.

    %seealso decode, transcode
    """
    ...

def decode(text: str, encoding: str = "utf-8") -> bytes:
    """Decode a string to bytes.

    %seealso encode
    """
    ...

The rendered docs show a “See Also” section with clickable links to each referenced item.

Adding Descriptions

Add a short description after each name, separated by a colon:

def load(path: str) -> dict:
    """Load data from a file.

    %seealso save : Write data back to a file, validate : Check data integrity
    """
    ...

Descriptions appear alongside the links. Entries with and without descriptions can be mixed freely.

Referencing Methods

Use dotted notation for class methods:

class Validator:
    def check(self, data):
        """Run all validation checks.

        %seealso Validator.reset, Report
        """
        ...

    def reset(self):
        """Clear all validation state.

        %seealso Validator.check
        """
        ...

Inline Interlinks

Create inline links to other API items anywhere in a docstring using the interlinks syntax:

Style	Syntax	Displays as
Shortened	[](`~mypackage.MyClass`)	`MyClass`
Full qualified	[](`mypackage.MyClass`)	`mypackage.MyClass`
Custom text	[see this class](`mypackage.MyClass`)	`see this class`
Custom + tilde	[see this class](`~mypackage.MyClass`)	`see this class`

The ~ prefix displays only the short name when no custom text is provided. Custom link text always takes priority.

class BaseStore:
    """Base class for all stores.

    Available implementations:

    - [](`~mypackage.DuckDBStore`): local storage with embedded search.
    - [](`~mypackage.ChromaDBStore`): vector storage using ChromaDB.

    See [](`mypackage.BaseStore`) for the full API, or
    [the DuckDB guide](`~mypackage.DuckDBStore`) for a walkthrough.
    """
    ...

Each reference becomes a clickable link to the target’s reference page.

Code Autolinks

Inline code matching a documented symbol is automatically linked — no special syntax needed:

class Engine:
    """Core processing engine.

    Use `Pipeline` to chain multiple engines together.
    Call `run_pipeline()` to execute a full pipeline.
    """
    ...

In the rendered output, `Pipeline` and `run_pipeline()` become clickable links.

Use ~~ to shorten qualified names: `~~mypackage.MyClass` displays as MyClass. Use `~~.mypackage.MyClass` for .MyClass.

To prevent autolinking, add {.gd-no-link}: `Config`{.gd-no-link}.

Tips

Names in %seealso must match the exported API name exactly
Multiple %seealso directives on the same symbol are merged
NumPy-style See Also sections are also recognized and merged with %seealso entries
The directive line is stripped from the rendered output
Unresolved references are shown as plain text (no broken links)
All GDLS features work in any part of a docstring (summary, parameters, notes, etc.)

%seealso Directive