# Cross-Reference Related Items

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:

``` python
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:

``` python
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:

``` python
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.

``` python
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):

``` python
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.)