sphinx-oceanid 0.1.0__tar.gz

sphinx_oceanid-0.1.0/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, driller
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

sphinx_oceanid-0.1.0/PKG-INFO

@@ -0,0 +1,180 @@
+Metadata-Version: 2.4
+Name: sphinx-oceanid
+Version: 0.1.0
+Summary: High-quality 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: 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)
+
+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.

sphinx_oceanid-0.1.0/README.md

@@ -0,0 +1,154 @@
+# 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.

sphinx_oceanid-0.1.0/pyproject.toml

@@ -0,0 +1,91 @@
+[project]
+name = "sphinx-oceanid"
+version = "0.1.0"
+description = "High-quality Mermaid diagrams in Sphinx, powered by beautiful-mermaid"
+readme = "README.md"
+license = "BSD-3-Clause"
+license-files = ["LICENSE"]
+requires-python = ">=3.13"
+keywords = ["sphinx", "mermaid", "diagrams", "documentation", "beautiful-mermaid"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Framework :: Sphinx :: Extension",
+    "License :: OSI Approved :: BSD License",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Documentation",
+]
+authors = [
+    { name = "driller", email = "eleshis@gmail.com" },
+]
+dependencies = [
+    "sphinx>=7.4",
+]
+
+[project.urls]
+Homepage = "https://github.com/drillan/sphinx-oceanid"
+Documentation = "https://drillan.github.io/sphinx-oceanid/"
+Repository = "https://github.com/drillan/sphinx-oceanid"
+"Bug Tracker" = "https://github.com/drillan/sphinx-oceanid/issues"
+Changelog = "https://github.com/drillan/sphinx-oceanid/blob/main/CHANGELOG.md"
+
+[build-system]
+requires = ["uv_build>=0.10.0,<0.11.0"]
+build-backend = "uv_build"
+
+[project.optional-dependencies]
+preview = ["sphinx-autobuild>=2024.0"]
+
+[dependency-groups]
+test = [
+    "pytest",
+    "myst-parser",
+    "sphinx-revealjs",
+]
+dev = [
+    "ruff",
+    "mypy",
+    "types-docutils",
+    { include-group = "test" },
+]
+docs = [
+    "myst-parser>=5.0.0",
+    "shibuya>=2026.1.9",
+    "sphinx>=9.1.0",
+    "sphinx-autobuild>=2024.0",
+    "sphinx-design>=0.6",
+    "sphinx-revealjs>=3.0",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 120
+target-version = "py313"
+
+[tool.ruff.lint]
+extend-select = [
+    "I",     # isort
+    "UP",    # pyupgrade
+    "B",     # flake8-bugbear
+    "SIM",   # flake8-simplify
+    "TCH",   # flake8-type-checking
+    "RUF",   # Ruff-specific
+    "PIE",   # flake8-pie
+    "PT",    # flake8-pytest-style
+    "RSE",   # flake8-raise
+    "C4",    # flake8-comprehensions
+    "FURB",  # refurb
+    "PERF",  # perflint
+]
+
+[tool.ruff.lint.isort]
+known-first-party = ["sphinx_oceanid"]
+
+[tool.mypy]
+python_version = "3.13"
+strict = true
+warn_unreachable = true
+enable_error_code = ["ignore-without-code", "redundant-cast", "truthy-bool"]
+exclude = ["tests/roots/", "examples/"]

sphinx_oceanid-0.1.0/src/sphinx_oceanid/__init__.py

@@ -0,0 +1,42 @@
+"""sphinx-oceanid: High-quality Mermaid diagrams in Sphinx."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from sphinx.application import Sphinx
+
+from importlib.metadata import version
+
+__version__ = version("sphinx-oceanid")
+
+_STATIC_DIR = str(Path(__file__).parent / "_static")
+
+
+def setup(app: Sphinx) -> dict[str, bool | str]:
+    """Sphinx extension entry point.
+
+    Registers nodes, directives, config values, and event handlers.
+    """
+    from .assets import install_assets
+    from .config import register_config_values, validate_config
+    from .directives import Mermaid, MermaidClassDiagram
+    from .nodes import mermaid_node
+    from .visitors import html_depart_mermaid, html_visit_mermaid
+
+    register_config_values(app)
+    app.add_node(mermaid_node, html=(html_visit_mermaid, html_depart_mermaid))
+    app.add_directive("mermaid", Mermaid)
+    app.add_directive("autoclasstree", MermaidClassDiagram)
+    app.connect("config-inited", validate_config)
+    app.connect("html-page-context", install_assets)
+    app.connect("builder-inited", _register_static_path)
+
+    return {"version": __version__, "parallel_read_safe": True}
+
+
+def _register_static_path(app: Sphinx) -> None:
+    """Register the extension's _static directory for file copying."""
+    app.config.html_static_path.append(_STATIC_DIR)

sphinx_oceanid-0.1.0/src/sphinx_oceanid/_static/oceanid-fullscreen.js

@@ -0,0 +1,127 @@
+/**
+ * sphinx-oceanid: Fullscreen modal for Mermaid diagrams (FR-018).
+ *
+ * Creates a modal overlay, injects fullscreen buttons on rendered diagrams,
+ * and watches for newly rendered diagrams via MutationObserver.
+ */
+
+/**
+ * Create the fullscreen modal DOM element and append to document body.
+ *
+ * @param {object} config - Oceanid config with fullscreenButton and fullscreenButtonOpacity
+ * @returns {{modal: HTMLElement, container: HTMLElement, close: Function}}
+ */
+const createModal = (config) => {
+  const modal = document.createElement("div");
+  modal.className = "oceanid-fullscreen-modal";
+
+  const closeBtn = document.createElement("button");
+  closeBtn.className = "oceanid-fullscreen-close";
+  closeBtn.textContent = "\u00d7";
+  closeBtn.setAttribute("aria-label", "Close fullscreen");
+
+  const container = document.createElement("div");
+  container.className = "oceanid-container-fullscreen";
+
+  modal.appendChild(closeBtn);
+  modal.appendChild(container);
+  document.body.appendChild(modal);
+
+  const close = () => {
+    modal.classList.remove("active");
+    container.innerHTML = "";
+  };
+
+  closeBtn.addEventListener("click", close);
+
+  modal.addEventListener("click", (e) => {
+    if (e.target === modal) {
+      close();
+    }
+  });
+
+  document.addEventListener("keydown", (e) => {
+    if (e.key === "Escape" && modal.classList.contains("active")) {
+      close();
+    }
+  });
+
+  return { modal, container, close };
+};
+
+/**
+ * Inject a fullscreen button on a rendered diagram element.
+ *
+ * @param {Element} el - .oceanid-diagram element with data-oceanid-rendered="true"
+ * @param {object} config - Oceanid config
+ * @param {{modal: HTMLElement, container: HTMLElement}} modalCtx - Modal context
+ */
+const addFullscreenButton = (el, config, modalCtx) => {
+  if (el.querySelector(".oceanid-fullscreen-btn")) {
+    return;
+  }
+
+  const wrapper = el.querySelector(".oceanid-svg-container");
+  if (!wrapper) {
+    return;
+  }
+
+  el.style.position = el.style.position || "relative";
+
+  const btn = document.createElement("button");
+  btn.className = "oceanid-fullscreen-btn";
+  btn.textContent = config.fullscreenButton;
+  btn.setAttribute("aria-label", "Open fullscreen");
+  btn.style.opacity = String(config.fullscreenButtonOpacity / 100);
+
+  btn.addEventListener("click", () => {
+    const svg = wrapper.querySelector("svg");
+    if (!svg) {
+      return;
+    }
+    modalCtx.container.innerHTML = "";
+    const clone = svg.cloneNode(true);
+    clone.style.width = "100%";
+    clone.style.height = "auto";
+    clone.style.maxHeight = "90vh";
+    modalCtx.container.appendChild(clone);
+    modalCtx.modal.classList.add("active");
+  });
+
+  el.appendChild(btn);
+};
+
+/**
+ * Set up fullscreen modal functionality.
+ *
+ * - Creates modal DOM and appends to body
+ * - Adds fullscreen button to already-rendered diagrams
+ * - Uses MutationObserver to add button to diagrams rendered later (lazy)
+ *
+ * @param {object} config - Oceanid config
+ */
+export const setupFullscreen = (config) => {
+  const modalCtx = createModal(config);
+
+  document
+    .querySelectorAll('.oceanid-diagram[data-oceanid-rendered="true"]')
+    .forEach((el) => {
+      addFullscreenButton(el, config, modalCtx);
+    });
+
+  const observer = new MutationObserver((mutations) => {
+    mutations.forEach((mutation) => {
+      if (
+        mutation.type === "attributes" &&
+        mutation.attributeName === "data-oceanid-rendered" &&
+        mutation.target.getAttribute("data-oceanid-rendered") === "true"
+      ) {
+        addFullscreenButton(mutation.target, config, modalCtx);
+      }
+    });
+  });
+
+  document.querySelectorAll(".oceanid-diagram").forEach((el) => {
+    observer.observe(el, { attributes: true });
+  });
+};