# API Documentation

Browse functions, classes, and module members. Open a signature to inspect its parameters and return values, or choose **Expand all**.

## Functions

### connect(host: str, port: int, , timeout: float = 30.0) → Connection

Connect to a remote server.

* **Parameters:**
  * **host** – The hostname or IP address.
  * **port** – The port number (1–65535).
  * **timeout** – Connection timeout in seconds.
* **Returns:**
  An active connection object.
* **Raises:**
  * **ConnectionError** – If the server is unreachable.
  * **ValueError** – If the port is out of range.

### Show the MyST source

```markdown
```{py:function} connect(host: str, port: int) -> Connection
Description of the function.

:param host: Parameter description.
:returns: Return value description.
:raises ConnectionError: When this error occurs.
```
```

## Classes

### *class* EventEmitter

A simple event emitter that supports registering handlers and emitting events.

#### EventEmitter.on(event: str, handler: Callable) → None

Register a handler for the given event name.

* **Parameters:**
  * **event** – The event name to listen for.
  * **handler** – A callable invoked when the event is emitted.

#### EventEmitter.emit(event: str, \*args, \*\*kwargs) → None

Emit an event, calling all registered handlers.

* **Parameters:**
  * **event** – The event name to emit.
  * **args** – Positional arguments passed to handlers.
  * **kwargs** – Keyword arguments passed to handlers.

#### EventEmitter.off(event: str, handler: Callable) → None

Remove a previously registered handler.

* **Parameters:**
  * **event** – The event name.
  * **handler** – The handler to remove.
* **Raises:**
  **ValueError** – If the handler is not registered for this event.

#### EventEmitter.handlers *: dict[str, list[Callable]]*

A mapping of event names to their registered handler lists.

### Show the MyST source for classes

```markdown
```{py:class} ClassName()
Class description.
```

```{py:method} ClassName.method_name(param: type) -> return_type
Method description.

:param param: Parameter description.
```
```

## Cross-Referencing API Items

Reference documented API items from anywhere using the `{py:func}`, `{py:class}`, and `{py:meth}` roles.

Use [`connect()`](#connect) to establish a connection, then create an [`EventEmitter`](#EventEmitter) instance and call [`EventEmitter.on()`](#EventEmitter.on) to register handlers.

The MyST syntax:

```markdown
{py:func}`connect`
{py:class}`EventEmitter`
{py:meth}`EventEmitter.on`
```

## Deprecation Notices

Mark API items as deprecated directly in their documentation.

### legacy_connect(host: str) → Connection

.. deprecated::
Use [`connect()`](#connect) instead, which supports timeout and port configuration.

## Module-Level Documentation

The main module for the Sphinx Lumina Theme.

### sphinx_lumina_theme.DEFAULT_ACCENT_COLOR *: str* *= #10b981*

The default accent color used when no custom `accent_color` is configured.

### sphinx_lumina_theme.SUPPORTED_SEARCH_BACKENDS *: tuple[str, ...]* *= ("pagefind", "sphinx")*

Tuple of supported search backend identifiers.

## Other Languages

Every Sphinx domain uses the same signature layout, so C, C++, JavaScript, and reStructuredText reference pages look and collapse like the Python ones.

### C

### struct lumina_config

Theme settings passed to [`lumina_render()`](#c.lumina_render).

### int lumina_render(const [lumina_config](#c.lumina_config) \*config, const char \*path)

Render a single page to disk.

* **Parameters:**
  * **config** – Theme settings to apply.
  * **path** – Output file path.
* **Returns:**
  `0` on success, a negative error code otherwise.

### LUMINA_MAX_DEPTH

Deepest navigation level rendered in the sidebar.

### C++

### template<typename T>class lumina::Cache

A fixed-size cache for rendered fragments.

### std::optional<T> lumina::[Cache](#_CPPv4I0EN6lumina5CacheE)::get(const std::string &key) const noexcept

Look up a cached fragment.

* **Parameters:**
  **key** – The fragment identifier.
* **Returns:**
  The cached value, or `std::nullopt` if the key is missing.

### JavaScript

### initSearch(selector, options)

Attach the search dialog to an input element.

* **Arguments:**
  * **selector** (*string*) – CSS selector for the search input.
  * **options** (*object*) – Search backend options.
* **Returns:**
  A handle with `open()` and `close()` methods.

### *class* ThemeToggle(root)

Switches between light, dark, and system color schemes.

* **Arguments:**
  * **root** (*HTMLElement*) – The element that receives `data-theme`.

### reStructuredText

Document your own directives and roles with the `rst` domain.

### .. lumina-card:: title

Render a linked card.

### :link: *target* *(document name or URL)*

Where the card points.

### :lumina-icon:

Insert an inline Lucide icon by name.

### Show the MyST source

```markdown
```{c:function} int lumina_render(const lumina_config *config, const char *path)
Render a single page to disk.

:param config: Theme settings to apply.
:returns: `0` on success.
```

```{cpp:class} template<typename T> lumina::Cache
A fixed-size cache for rendered fragments.
```

```{js:function} initSearch(selector, options)
Attach the search dialog to an input element.

:param string selector: CSS selector for the search input.
```

```{rst:directive} .. lumina-card:: title
Render a linked card.
```
```

## Using autodoc

For real projects, you’ll typically generate API docs from your source code using `sphinx.ext.autodoc` instead of writing signatures by hand.

### Setup

```python
extensions = [
    "sphinx.ext.autodoc",
    "sphinx.ext.napoleon",     # Google/NumPy docstring support
    "sphinx.ext.viewcode",     # Link to highlighted source
]
```

### Documenting a Module

Create a `.md` or `.rst` file and use the `automodule`, `autoclass`, or `autofunction` directives:

```markdown
## API Reference

```{automodule} mypackage.core
:members:
:undoc-members:
:show-inheritance:
```
```

### Documenting Individual Items

```markdown
```{autofunction} mypackage.connect
```

```{autoclass} mypackage.EventEmitter
:members:
:special-members: __init__
```
```

### autodoc Options

| Option                | Description                                                     |
|-----------------------|-----------------------------------------------------------------|
| `:members:`           | Include all public members.                                     |
| `:undoc-members:`     | Include members without docstrings.                             |
| `:private-members:`   | Include `_private` members.                                     |
| `:special-members:`   | Include `__dunder__` methods (specify which, e.g., `__init__`). |
| `:show-inheritance:`  | Show base classes.                                              |
| `:inherited-members:` | Include members inherited from base classes.                    |
| `:exclude-members:`   | Comma-separated list of members to skip.                        |