Metadata-Version: 2.4
Name: sphinx-oceanid
Version: 0.2.0
Summary: Mermaid diagrams in Sphinx, powered by beautiful-mermaid
Keywords: sphinx,mermaid,diagrams,documentation,beautiful-mermaid
Author: driller
Author-email: driller <eleshis@gmail.com>
License-Expression: BSD-3-Clause
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: Sphinx :: Extension
Classifier: License :: OSI Approved :: BSD License
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Documentation
Requires-Dist: pyyaml
Requires-Dist: sphinx>=7.4
Requires-Dist: sphinx-autobuild>=2024.0 ; extra == 'preview'
Requires-Python: >=3.13
Project-URL: Homepage, https://github.com/drillan/sphinx-oceanid
Project-URL: Documentation, https://drillan.github.io/sphinx-oceanid/
Project-URL: Repository, https://github.com/drillan/sphinx-oceanid
Project-URL: Bug Tracker, https://github.com/drillan/sphinx-oceanid/issues
Project-URL: Changelog, https://github.com/drillan/sphinx-oceanid/blob/main/CHANGELOG.md
Provides-Extra: preview
Description-Content-Type: text/markdown

# 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)

Mermaid diagrams in Sphinx, powered by [beautiful-mermaid](https://github.com/lukilabs/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
- **YAML frontmatter** — Set title and per-diagram config via Mermaid frontmatter in `.mmd` files and RST
- **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 .
```

## Claude Code Skill (Optional)

This repository ships a [`mermaid-diagram`](skills/mermaid-diagram/SKILL.md) skill for AI coding agents. It provides proactive diagram suggestions, syntax validation, and ready-made examples for all 6 supported diagram types.

Install it with [`gh skill install`](https://docs.github.com/en/copilot/customizing-copilot/agent-skills) (preview, requires GitHub CLI 2.91+):

```bash
gh skill install drillan/sphinx-oceanid mermaid-diagram --agent claude-code
```

Supported `--agent` values: `claude-code`, `github-copilot`, `cursor`, `codex`, `gemini`, `antigravity`.

Use `--scope user` to install globally instead of per-project. See [docs/install.md](docs/install.md#claude-code-skill) for details, version pinning, and update workflow.

## 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!
```
````

Build and preview — Mermaid diagrams require HTTP serving (`file://` will not render due to CORS):

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

## 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: True)
oceanid_zoom = False

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

# 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
```

## YAML Frontmatter

External `.mmd` files can include YAML frontmatter to set the diagram title and per-diagram rendering options:

```yaml
---
title: User Authentication Flow
config:
  bg: "#1a1b26"
  fg: "#a9b1d6"
---
flowchart TD
  A[Login Page] --> B{Valid credentials?}
  B -->|Yes| C[Dashboard]
  B -->|No| D[Error Message]
```

Frontmatter is also supported in RST inline content. In MyST Markdown, use directive options with JSON format for `config`. See the [documentation](https://drillan.github.io/sphinx-oceanid/) for details.

## Auto Class Diagrams

Generate class hierarchy diagrams from Python code:

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

## 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.
