#260 gdtest_interlinks

"""Package demonstrating interlinks in docstring prose and user-guide pages."""

__version__ = "0.1.0"
__all__ = ["BaseStore", "DuckDBStore", "ChromaDBStore", "query"]


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

    Available implementations:

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

    Parameters
    ----------
    name
        The name of the store.
    """

    def __init__(self, name: str) -> None:
        self.name = name


class DuckDBStore(BaseStore):
    """Local storage backed by DuckDB.

    Inherits from [](`~gdtest_interlinks.BaseStore`).
    Use [](`~gdtest_interlinks.query`) to search the store
    after loading data.

    Parameters
    ----------
    name
        The name of the store.
    path
        Path to the DuckDB database file.
    """

    def __init__(self, name: str, path: str = ":memory:") -> None:
        super().__init__(name)
        self.path = path


class ChromaDBStore(BaseStore):
    """Vector storage using ChromaDB.

    Inherits from [](`gdtest_interlinks.BaseStore`).
    See [the DuckDB-backed store](`~gdtest_interlinks.DuckDBStore`) for a
    simpler alternative.

    Parameters
    ----------
    name
        The name of the store.
    collection
        The ChromaDB collection name.
    """

    def __init__(self, name: str, collection: str = "default") -> None:
        super().__init__(name)
        self.collection = collection


def query(store: BaseStore, text: str) -> list:
    """Search a store for matching documents.

    Works with any [](`~gdtest_interlinks.BaseStore`)
    implementation, including
    [](`gdtest_interlinks.DuckDBStore`) and
    [the ChromaDB store](`gdtest_interlinks.ChromaDBStore`).

    Parameters
    ----------
    store
        The store to search. Must be an instance of
        [a base store](`~gdtest_interlinks.BaseStore`).
    text
        The search query string.

    Returns
    -------
    list
        Matching documents.
    """
    return []

---
title: Getting Started
---

## Creating a Store

To store and search documents, first create a
[](`~gdtest_interlinks.DuckDBStore`) instance:

```python
from gdtest_interlinks import DuckDBStore
store = DuckDBStore("my-store")
```

## Checking the Base Interface

Every store implements the
[](`~gdtest_interlinks.BaseStore`) interface:

```python
isinstance(store, BaseStore)
```

## Running Queries

Call [](`~gdtest_interlinks.query`) to search:

```python
results = query(store, "hello")
```

See the [API Reference](../reference/index.qmd) for full details.

---
title: Advanced Usage
---

## Full Qualified References

You can reference the full path:
[](`gdtest_interlinks.BaseStore`).

## Custom Link Text

Or use [custom link text](`gdtest_interlinks.DuckDBStore`)
for any reference.

## Custom Text with Tilde

And also [custom text with tilde](`~gdtest_interlinks.ChromaDBStore`)
to override display.

## Autolinked Code

Inline code like `BaseStore` and `DuckDBStore` and `query()`
is automatically linked to reference pages.

---
title: External Links
---

# External Links

Another project's objects are referenced the same way as our own:
[](`extdemo.Widget`) names it in full, and [](`ed.Widget`) uses the
alias the source declares.