# sphinx-oceanid

[![PyPI](https://img.shields.io/pypi/v/sphinx-oceanid)](https://pypi.org/project/sphinx-oceanid/)
[![Python](https://img.shields.io/pypi/pyversions/sphinx-oceanid)](https://pypi.org/project/sphinx-oceanid/)
[![Documentation](https://img.shields.io/badge/docs-GitHub%20Pages-blue)](https://drillan.github.io/sphinx-oceanid/)
[![日本語](https://img.shields.io/badge/lang-日本語-red)](README.ja.md)

High-quality Mermaid diagrams in Sphinx, powered by [beautiful-mermaid](https://github.com/niccolozy/beautiful-mermaid).

## Features

- **beautiful-mermaid rendering** — Uses ELK.js-based layout engine for high-quality SVG output
- **CSS variable theming** — Automatic dark/light theme detection with instant switching (no re-render)
- **Zero-config** — Works out of the box with CDN-hosted beautiful-mermaid
- **sphinx-revealjs support** — Lazy rendering for hidden slides via IntersectionObserver ([example](https://drillan.github.io/sphinx-oceanid/slides/))
- **Pan & zoom** — Native Pointer Events + SVG transform (no d3.js dependency)
- **Fullscreen modal** — View diagrams in a viewport-sized overlay
- **External file support** — Reference `.mmd` files instead of inline code
- **Auto class diagrams** — Generate class hierarchy diagrams from Python code

## Supported Diagram Types

| Type | Alias |
|------|-------|
| `flowchart` | `graph` |
| `sequenceDiagram` | |
| `classDiagram` | |
| `stateDiagram` | `stateDiagram-v2` |
| `erDiagram` | |
| `xychart-beta` | |

Unsupported diagram types produce explicit warnings (or errors), never silent degradation.

## Installation

sphinx-oceanid requires Python 3.13+.

```bash
pip install sphinx-oceanid
```

From source:

```bash
pip install git+https://github.com/drillan/sphinx-oceanid.git
```

Or clone and install locally:

```bash
git clone https://github.com/drillan/sphinx-oceanid.git
cd sphinx-oceanid
pip install .
```

## Quick Start

Add the extension to your `conf.py`:

```python
extensions = ["sphinx_oceanid"]
```

Then use the `mermaid` directive in your reStructuredText files:

```rst
.. mermaid::

   flowchart LR
     A[Start] --> B[Process] --> C[End]
```

Or in Markdown (MyST) files:

````markdown
```{mermaid}
sequenceDiagram
  Alice->>Bob: Hello
  Bob-->>Alice: Hi!
```
````

## Configuration

All configuration options use the `oceanid_` prefix in `conf.py`:

```python
# conf.py
extensions = ["sphinx_oceanid"]

# Theme (default: "auto" — detects dark/light from Sphinx theme)
oceanid_theme = "auto"
oceanid_theme_dark = "zinc-dark"
oceanid_theme_light = "zinc-light"

# Enable zoom on all diagrams (default: False)
oceanid_zoom = True

# Enable fullscreen modal (default: False)
oceanid_fullscreen = True

# Action for unsupported diagram types: "warning" or "error" (default: "warning")
oceanid_unsupported_action = "warning"
```

## Directive Options

```rst
.. mermaid::
   :name: my-diagram
   :alt: Description for accessibility
   :align: center
   :caption: Diagram caption (rendered as <figcaption>)
   :title: Mermaid native title (rendered inside the diagram)
   :zoom:
   :config: {"theme": "forest"}

   flowchart LR
     A --> B --> C
```

## Auto Class Diagrams

Generate class hierarchy diagrams from Python code:

```rst
.. autoclasstree:: mypackage.MyClass
   :full:
   :namespace: mypackage
   :caption: Class hierarchy
```

## Local Preview

Mermaid diagrams require HTTP serving — opening built HTML via `file://` will not render diagrams due to browser CORS restrictions.

```bash
# Quick static server (no extra dependencies)
make -C docs serve

# Live reload (requires sphinx-autobuild)
pip install sphinx-oceanid[preview]
make -C docs livehtml
```

See [docs/install.md](docs/install.md) for Makefile setup instructions.

## Documentation

Full documentation is available at **[drillan.github.io/sphinx-oceanid](https://drillan.github.io/sphinx-oceanid/)** or in the [docs/](docs/) directory.

## License

BSD-3-Clause. See [LICENSE](LICENSE) for details.
