pax_global_header 0000666 0000000 0000000 00000000064 15126273300 0014511 g ustar 00root root 0000000 0000000 52 comment=ce5c07b1f747948e5cb138a03834872a6074b57b
sphinxcontrib-mermaid-2.0.0/ 0000775 0000000 0000000 00000000000 15126273300 0016016 5 ustar 00root root 0000000 0000000 sphinxcontrib-mermaid-2.0.0/.github/ 0000775 0000000 0000000 00000000000 15126273300 0017356 5 ustar 00root root 0000000 0000000 sphinxcontrib-mermaid-2.0.0/.github/dependabot.yml 0000664 0000000 0000000 00000001103 15126273300 0022201 0 ustar 00root root 0000000 0000000 # Keep GitHub Actions up to date with GitHub's Dependabot...
# https://docs.github.com/en/code-security/dependabot/working-with-dependabot/keeping-your-actions-up-to-date-with-dependabot
# https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file#package-ecosystem
version: 2
updates:
- package-ecosystem: github-actions
directory: /
groups:
github-actions:
patterns:
- "*" # Group all Actions updates into a single larger pull request
schedule:
interval: weekly
sphinxcontrib-mermaid-2.0.0/.github/workflows/ 0000775 0000000 0000000 00000000000 15126273300 0021413 5 ustar 00root root 0000000 0000000 sphinxcontrib-mermaid-2.0.0/.github/workflows/release.yml 0000664 0000000 0000000 00000001114 15126273300 0023553 0 ustar 00root root 0000000 0000000 name: Publish Python 🐍 distributions 📦 to PyPI
on:
push:
tags:
- "*"
jobs:
pypi-publish:
name: upload release to PyPI
runs-on: ubuntu-latest
if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags')
permissions:
id-token: write
steps:
- name: Checkout
uses: actions/checkout@v6
- name: install build
run: python -m pip install --upgrade build
- name: build
run: python -m build
- name: Publish package distributions to PyPI
uses: pypa/gh-action-pypi-publish@release/v1 sphinxcontrib-mermaid-2.0.0/.github/workflows/test.yml 0000664 0000000 0000000 00000001550 15126273300 0023116 0 ustar 00root root 0000000 0000000 name: Test
on: [push, pull_request, workflow_dispatch]
env:
FORCE_COLOR: 1
jobs:
test:
runs-on: ${{ matrix.os }}
strategy:
fail-fast: false
matrix:
python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
os: [windows-latest, macos-latest, ubuntu-latest]
steps:
- uses: actions/checkout@v6
- name: Set up Python ${{ matrix.python-version }}
uses: actions/setup-python@v6
with:
python-version: ${{ matrix.python-version }}
allow-prereleases: true
cache: pip
cache-dependency-path: pyproject.toml
- name: Install dependencies
run: |
python -m pip install -e .[test]
- name: Lint
run: |
ruff format --check sphinxcontrib
ruff check sphinxcontrib
- name: Test
run: |
pytest
sphinxcontrib-mermaid-2.0.0/.gitignore 0000664 0000000 0000000 00000002270 15126273300 0020007 0 ustar 00root root 0000000 0000000 # Byte-compiled / optimized / DLL files
__pycache__/
*.py[cod]
*$py.class
# C extensions
*.so
# Distribution / packaging
.Python
env/
build/
_build/
_static/
_templates/
develop-eggs/
dist/
downloads/
eggs/
.eggs/
lib/
lib64/
parts/
sdist/
var/
*.egg-info/
.installed.cfg
*.egg
# PyInstaller
# Usually these files are written by a python script from a template
# before PyInstaller builds the exe, so as to inject date/other infos into it.
*.manifest
*.spec
# Installer logs
pip-log.txt
pip-delete-this-directory.txt
# Unit test / coverage reports
htmlcov/
.tox/
.coverage
.coverage.*
.cache
nosetests.xml
coverage.xml
*,cover
.hypothesis/
# Translations
*.mo
*.pot
# Django stuff:
*.log
local_settings.py
# Flask stuff:
instance/
.webassets-cache
# Scrapy stuff:
.scrapy
# Sphinx documentation
docs/index.md
docs/_build/
# PyBuilder
target/
# IPython Notebook
.ipynb_checkpoints
# pyenv
.python-version
# celery beat schedule file
celerybeat-schedule
# dotenv
.env
# virtualenv
venv/
ENV/
# Spyder project settings
.spyderproject
.spyproject
# Rope project settings
.ropeproject
# IDEA project settings
.idea
# Test directories (for manual theme testing)
test-fullscreen/
theme-tests/
sphinxcontrib-mermaid-2.0.0/.readthedocs.yaml 0000664 0000000 0000000 00000001256 15126273300 0021251 0 ustar 00root root 0000000 0000000 # .readthedocs.yaml
# Read the Docs configuration file
# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
# Required
version: 2
# Set the version of Python and other tools you might need
build:
os: ubuntu-24.04
apt_packages:
- libasound2t64
tools:
python: "3"
nodejs: "20"
jobs:
post_install:
- npm install -g @mermaid-js/mermaid-cli
# Build documentation in the docs/ directory with Sphinx
sphinx:
configuration: docs/conf.py
# If using Sphinx, optionally build your docs in additional formats such as PDF
formats:
- epub
- pdf
python:
install:
- requirements: docs/requirements.txt
- method: pip
path: . sphinxcontrib-mermaid-2.0.0/CHANGELOG.md 0000664 0000000 0000000 00000010130 15126273300 0017622 0 ustar 00root root 0000000 0000000 # Changelog
## 2.0.0 (TBD)
- Drop support for Python 3.8 and 3.9
- Add support for dynamic theme changes
## 1.2.3 (November 25, 2025)
- Fix issue with ELK charts by upgrading to ELK plugin
[0.2.0]{.title-ref}
## 1.2.2 (November 23, 2025)
- Hotfix for CSS/JS assets included via old MANIFEST mechanism
## 1.2.1 (November 23, 2025)
- Adjust chart size defaults to closer resember previous
- Fix issue with fullscreen classes after rebase
## 1.2.0 (November 23, 2025)
- Normalize javascript across various configuration options
- Make graph full width and avoid unused margins in graph image
- Rename fullscreen container class from
[mermaid-fullscreen-content]{.title-ref} to
[mermaid-container-fullscreen]{.title-ref}
## 1.1.0 (November 19, 2025)
- Upgrade Mermaid to 11.12.1
- Add fullscreen graph view capabilities
## 1.0.0 (October 12, 2024)
- Upgrade Mermaid to 11.2.0
- Add support for ELK diagrams
- Add support for name parameter
- Add passthrough of mermaid frontmatter
- Convert to native namespace package
- Drop support for Python 3.7
- Convert default placeholder from div to pre
- Fix for tempfile encoding when containing non ascii characters
- Fix for mermaid sequence config arguments
- Default to jsdelivr (previously unpkg) for JS asset CDN
See full [set of changes](https://github.com/mgaitan/sphinxcontrib-mermaid/compare/1.0.0...0.9.2).
## 0.9.2 (May 28, 2023)
- Implemented zoom on diagrams functionality. Contributed by [Daniel
Althviz Moré](https://github.com/dalthviz)
- Fix a bug on empty diagram generations. Contributed by [Kevin
Deldycke](https://github.com/kdeldycke).
- Upgrade default to Mermaid 10.2.0.
- Implement automatic releases from Github Actions when a tag is pushed
See full [set of
changes](https://github.com/mgaitan/sphinxcontrib-mermaid/compare/0.9.2...0.8.1).
## 0.8.1 (Feb 25, 2023)
- Default to Mermaid 9.4.0 as 10.0 introduced incompatible changes. See
[the
discussion](https://github.com/mermaid-js/mermaid/discussions/4148).
## 0.8 (Feb 9, 2023)
- Moved CI to Github Actions
- Make the class diagram reproducible
- Allow the user to change the JS priority
- Drop support for Python 3.6
- Black formatting
See [full set of
changes](https://github.com/mgaitan/sphinxcontrib-mermaid/compare/0.7.1...0.8).
## 0.7.1 (July 17, 2021)
- Update docs and tests for markdown support
## 0.7 (May 31, 2021)
- Add compatibility with Sphinx 4.0
- [mermaid_init_js]{.title-ref} is now included in an standard way.
- Documented how to use in Markdown documents
## 0.6.3 (February 21, 2021)
- Make it compatible with recent Sphinx versions
- Add basic (real) tests (So I stop breaking it!)
## 0.6.2 (February 18, 2021)
- fix regression
- setup travis
## 0.6.1 (February 8, 2021)
- Fix a problem when called mermaid-cli
- Fix typos on documentation
- Improve internal code formatting (via black)
## 0.6.0 (January 31, 2021)
- Drop support for Python version older than 3.6.
- Allow to include javascript lib locally
- Initialization code is now customizable
- The default version included from the CDN is always the latest
available.
## 0.5.0 (September 24, 2020)
- Added mermaid_cmd_shell. Useful for Windows user.
- Reimplement inheritance diagrams.
- Fix UnicodeEncodeError on Python 2
## 0.4.0 (April 9, 2020)
- Added [mermaid_params]{.title-ref}
- Added config file option
- Improved latex integration
- Added the [pdfcrop]{.title-ref} functionality
- Mermaid version is configurable
- Several cleanups in the code
## 0.3.1 (Nov 22, 2017)
- Support the new Mermaid CLI by [Bastian
Luettig](https://github.com/bastiedotorg)
## 0.3 (Oct 4, 2017)
- several improves and bugfixes contributed by [Alberto
Berti](https://github.com/azazel75)
## 0.2.1 (Jun 4, 2017)
- Workaround for opacity issue with rtd's theme (thanks to [Anton
Koldaev](http://github.com/iroller))
## 0.2 (Jun 4, 2017)
- Python 3 support fix (thanks to [Shakeeb
Alireza](http://github.com/shakfu))
- In-browser diagram generation
- Autoclasstree directive. (Thanks to [Zulko](http://github.com/zulko))
## 0.1.1 (Jun 4, 2017)
- Better usage instructions
- Bugfix
## 0.1 (Jul 18, 2016)
- first public version
sphinxcontrib-mermaid-2.0.0/LICENSE 0000664 0000000 0000000 00000002526 15126273300 0017030 0 ustar 00root root 0000000 0000000 sphinxcontrib-mermaid is a Sphinx extension for Mermaid Diagrams
Copyright (c) 2016 by Martín Gaitán
All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are
met:
- Redistributions of source code must retain the above copyright notice,
this list of conditions and the following disclaimer.
- 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.
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 OWNER
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.
sphinxcontrib-mermaid-2.0.0/MANIFEST.in 0000664 0000000 0000000 00000000331 15126273300 0017551 0 ustar 00root root 0000000 0000000 include README.rst
include CHANGELOG.rst
include LICENSE.rst
# Include static assets (CSS and JavaScript)
recursive-include sphinxcontrib/mermaid *.css.j2 *.js.j2
prune tests
exclude .gitignore
global-exclude *.pyc
sphinxcontrib-mermaid-2.0.0/README.md 0000664 0000000 0000000 00000027502 15126273300 0017303 0 ustar 00root root 0000000 0000000 > [!NOTE]
> `sphinxcontrib-mermaid` is actively seeking new maintainers.
> As the original creator, I'm no longer able to dedicate the time and
> attention needed. If you're interested in contributing and helping to
> drive this project forward, please see [this
> issue](https://github.com/mgaitan/sphinxcontrib-mermaid/issues/148).
# sphinxcontrib-mermaid
[](https://github.com/mgaitan/sphinxcontrib-mermaid/actions/workflows/test.yml)
[](https://pypi.org/project/sphinxcontrib-mermaid/)
[](https://libraries.io/pypi/sphinxcontrib-mermaid/)
This extension allows you to embed [Mermaid](https://mermaid.js.org/)
graphs in your documents, including general flowcharts, sequence
diagrams, gantt diagrams and more.
It adds a directive to embed mermaid markup. For example:
```rst
.. mermaid::
sequenceDiagram
participant Alice
participant Bob
Alice->John: Hello John, how are you?
loop Healthcheck
John->John: Fight against hypochondria
end
Note right of John: Rational thoughts prevail...
John-->Alice: Great!
John->Bob: How about you?
Bob-->John: Jolly good!
```
By default, the HTML builder will simply render this as a `div` tag with
`class="mermaid"`, injecting the external javascript, css and
initialization code to make mermaid works.
For other builders (or if `mermaid_output_format` config variable is set
differently), the extension will use
[mermaid-cli](https://github.com/mermaid-js/mermaid-cli) to render as to
a PNG or SVG image, and then used in the proper code.
```mermaid
sequenceDiagram
participant Alice
participant Bob
Alice->John: Hello John, how are you?
loop Healthcheck
John->John: Fight against hypochondria
end
Note right of John: Rational thoughts prevail...
John-->Alice: Great!
John->Bob: How about you?
Bob-->John: Jolly good!
```
You can also embed external mermaid files, by giving the file name as an
argument to the directive and no additional content:
```rst
.. mermaid:: path/to/mermaid-gantt-code.mmd
```
As for all file references in Sphinx, if the filename is not absolute,
it is taken as relative to the source directory.
In addition, you can use mermaid to automatically generate a diagram to
show the class inheritance using the directive `autoclasstree`. It
accepts one or more fully qualified names to a class or a module. In the
case of a module, all the class found will be included.
Of course, these objects need to be importable to make its diagram.
If an optional attribute `:full:` is given, it will show the complete
hierarchy of each class.
The option `:namespace: ` limits to the base classes that belongs
to this namespace. Meanwhile, the flag `:strict:` only process the
classes that are strictly defined in the given module (ignoring classes
imported from other modules).
For example:
```rst
.. autoclasstree:: sphinx.util.DownloadFiles sphinx.util.ExtensionError
:full:
```
```{eval-rst}
.. autoclasstree:: sphinx.util.DownloadFiles sphinx.util.ExtensionError
:full:
```
Or directly the module:
```rst
.. autoclasstree:: sphinx.util
```
```{eval-rst}
.. autoclasstree:: sphinx.util
```
## Installation
You can install it using pip
```bash
pip install sphinxcontrib-mermaid
```
Then add `sphinxcontrib.mermaid` in `extensions` list of your project's
`conf.py`:
```python
extensions = [
...,
'sphinxcontrib.mermaid'
]
```
## Directive options
`sphinxcontrib-mermaid` mermaid diagrams can be configured by `rst`/`md` frontmatter:
```rst
.. mermaid::
:name: test
```
````markdown
```mermaid
---
name: test
---
````
- `name`: determines the image's name for HTML output. **NOTE**: mermaid will use this as the `id` of the generated `svg` element, which can be useful for styling with custom css: `#mydiagram > svg { height: 1000px }`
- `alt`: determines the image's alternate text for HTML output. If not given, the alternate text defaults to the mermaid code.
- `align`: determines the image's position. Valid options are `'left'`, `'center'`, `'right'`
- `caption`: can be used to give a caption to the diagram.
- `zoom`: can be used to enable zooming the diagram. For a global config see `mermaid_d3_zoom` below.
- `fullscreen`: can be used to enable fullscreen modal viewing of the diagram. For a global config see `mermaid_fullscreen` below.
- `config`: JSON to pass through to the [mermaid configuration](https://mermaid.js.org/config/configuration.html). **NOTE**: The mermaid documentation uses YAML, but we must use JSON because Markdown processing of frontmatter will interfere.
- `title`: Title to pass through to the [mermaid configuration](https://mermaid.js.org/config/configuration.html)
## Config values
### `mermaid_output_format`
The output format for Mermaid when building HTML files. This must be
either `'raw'` `'png'` or `'svg'`; the default is `'raw'`.
`mermaid-cli` is required if it's not `raw`
### `mermaid_cmd`
The command name with which to invoke `mermaid-cli` program. The
default is `'mmdc'`; you may need to set this to a full path if it's
not in the executable search path. If a string is specified, it is
split using [shlex.split]{.title-ref} to support multi-word commands.
To avoid splitting, a list of strings can be specified. Examples:
```python
mermaid_cmd = 'npx mmdc'
mermeid_cmd = ['npx', '--no-install', 'mmdc']
```
### `mermaid_cmd_shell`
When set to true, the `shell=True` argument will be passed the process
execution command. This allows commands other than binary executables
to be executed on Windows. The default is false.
### `mermaid_params`
For individual parameters, a list of parameters can be added. Refer to
[Examples](https://github.com/mermaid-js/mermaid-cli#usage):
```python
mermaid_params = ['--theme', 'forest', '--width', '600', '--backgroundColor', 'transparent']
```
This will render the mermaid diagram with theme forest, 600px width
and transparent background.
### `mermaid_sequence_config`
Allows overriding the sequence diagram configuration. It could be
useful to increase the width between actors. It **needs to be a json
file** Check options in the [documentation](https://mermaid-js.github.io/mermaid/#/mermaidAPI?id=configuration)
### `mermaid_verbose`
Use the verbose mode when call mermaid-cli, and show its output in the
building process.
### `mermaid_pdfcrop`
If using latex output, it might be useful to crop the pdf just to the
needed space. For this, `pdfcrop` can be used. State binary name to
use this extra function.
### `mermaid_init_config`
Optional override of arguments to `mermaid.initialize()`, passed in as
a JSON. Defaults to `{ "startOnLoad": True}`.
### `mermaid_version`
The version of mermaid that will be used to parse `raw` output in HTML
files. This should match a version available on
[https://www.jsdelivr.com/package/npm/mermaid](https://www.jsdelivr.com/package/npm/mermaid).
The default is `"11.12.1"`.
### `mermaid_use_local`
Optional path to a local installation of `mermaid.esm.min.mjs`. By
default, we will pull from jsdelivr.
### `mermaid_include_elk`
Whether to download and load the ELK JavaScript extensions. Defaults
to False.
### `mermaid_include_zenuml`
Whether to download and load the ZenuML JavaScript extensions.
Defaults to False.
### `mermaid_elk_version`
The version of mermaid ELK renderer that will be used. The default is
`"0.2.0"`.
### `mermaid_zenuml_version`
The version of mermaid ZenuML renderer that will be used. The default
is `"0.2.2"`.
### `mermaid_elk_use_local`
Optional path to a local installation of
`mermaid-layout-elk.esm.min.mjs`. By default, we will pull from
jsdelivr.
### `mermaid_zenuml_use_local`
Optional path to a local installation of `mermaid-zenuml.esm.min.mjs`.
By default, we will pull from jsdelivr.
### `d3_use_local`
Optional path to a local installation of `d3.min.js`. By default, we
will pull from jsdelivr.
### `d3_version`
The version of d3 that will be used to provide zoom functionality on
mermaid graphs. The default is `"7.9.0"`.
### `mermaid_d3_zoom`
Enables zooming in all the generated Mermaid diagrams.
### `mermaid_width`
Sets the default diagram width within its container. Default to 100%.
### `mermaid_height`
Sets the default diagram height within its container. Default to
500px.
### `mermaid_fullscreen`
Enables fullscreen modal viewing for all Mermaid diagrams. When
enabled, a fullscreen button appears in the top-right corner of each
diagram. Clicking it opens the diagram in a fullscreen modal overlay.
The modal can be closed by pressing ESC, clicking outside the diagram,
or clicking the close button. This feature is theme-agnostic and works
with any Sphinx theme.
### `mermaid_fullscreen_button`
Customizes the fullscreen button icon/text. Default is `"⛶"`. You can
use any Unicode character or emoji, for example `"🔍"` or `"⛶"`.
### `mermaid_fullscreen_button_opacity`
Customizes the fullscreen button opacity, to avoid fully obscuring
important chart content. Default is `50` (percent). You can use any
value from 0 to 100. Button becomes fully opaque on hover.
## Markdown support
You can include Mermaid diagrams in your Markdown documents in Sphinx.
You just need to setup the [markdown support in
Sphinx](https://www.sphinx-doc.org/en/master/usage/markdown.html) via
[myst-parser](https://myst-parser.readthedocs.io/) . See a [minimal
configuration from the
tests](https://github.com/mgaitan/sphinxcontrib-mermaid/blob/master/tests/roots/test-markdown/conf.py).
Then in your `.md` documents include a code block as in
reStructuredTexts:
````markdown
```{mermaid}
sequenceDiagram
participant Alice
participant Bob
Alice->John: Hello John, how are you?
```
````
For GitHub cross-support, you can omit the curly braces and configure
myst to use the [mermaid]{.title-ref} code block as a myst directive.
For example, in \`conf.py\`:
```python
myst_fence_as_directive = ["mermaid"]
```
## Building PDFs on readthedocs.io
In order to have Mermaid diagrams build properly in PDFs generated on
readthedocs.io, you will need a few extra configurations.
1. In your `.readthedocs.yaml` file (which should be in the root of your repository) include a `post-install` command to the Mermaid CLI:
```yaml
build:
os: ubuntu-20.04
tools:
python: "3.8"
nodejs: "16"
jobs:
post_install:
- npm install -g @mermaid-js/mermaid-cli
```
Note that if you previously did not have a `.readthedocs.yaml` file,
you will also need to specify all targets you wish to build and other
basic configuration options. A minimal example of a complete file is:
```yaml
# .readthedocs.yaml
# Read the Docs configuration file
# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
# Required
version: 2
# Set the version of Python and other tools you might need
build:
os: ubuntu-24.04
apt_packages:
- libasound2t64
tools:
python: "3.11"
nodejs: "20"
jobs:
post_install:
- npm install -g @mermaid-js/mermaid-cli
# Build documentation in the docs/ directory with Sphinx
sphinx:
configuration: docs/conf.py
# If using Sphinx, optionally build your docs in additional formats such as PDF
formats:
- epub
- pdf
python:
install:
- requirements: docs/requirements.txt
```
2. In your documentation directory add file `puppeteer-config.json` with contents: :
```json
{
"args": ["--no-sandbox"]
}
```
3. In your documentation `conf.py` file, add: :
```python
mermaid_params = ['-p', 'puppeteer-config.json']
```
sphinxcontrib-mermaid-2.0.0/docs/ 0000775 0000000 0000000 00000000000 15126273300 0016746 5 ustar 00root root 0000000 0000000 sphinxcontrib-mermaid-2.0.0/docs/Makefile 0000664 0000000 0000000 00000001266 15126273300 0020413 0 ustar 00root root 0000000 0000000 # Minimal makefile for Sphinx documentation
#
# You can set these variables from the command line.
SPHINXOPTS =
SPHINXBUILD = sphinx-build
SPHINXPROJ = Sphinxcontrib-mermaiddemo
SOURCEDIR = .
BUILDDIR = _build
# Put it first so that "make" without argument is like "make help".
help:
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
.PHONY: help Makefile
open:
python -m webbrowser -t "file://$(PWD)/_build/html/index.html"
# Catch-all target: route all unknown targets to Sphinx using the new
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
%: Makefile
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
sphinxcontrib-mermaid-2.0.0/docs/conf.py 0000664 0000000 0000000 00000006055 15126273300 0020253 0 ustar 00root root 0000000 0000000 #!/usr/bin/env python3
from pathlib import Path
extensions = [
"myst_parser",
"sphinxcontrib.mermaid",
"sphinx.ext.imgconverter",
]
templates_path = ["_templates"]
source_suffix = [".md"]
master_doc = "index"
project = "sphinxcontrib-mermaid"
copyright = "2017-2025, Martín Gaitán"
author = "Martín Gaitán"
version = "2.0"
release = "2.0.0rc1"
exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
pygments_style = "sphinx"
todo_include_todos = False
html_theme = "furo"
html_static_path = ["_static"]
htmlhelp_basename = "sphinxcontrib-mermaiddoc"
latex_documents = [
(master_doc, "sphinxcontrib-mermaid.tex", "sphinxcontrib-mermaid documentation", "Martín Gaitán", "manual"),
]
man_pages = [(master_doc, "sphinxcontrib-mermaid", "sphinxcontrib-mermaid documentation", [author], 1)]
texinfo_documents = [
(
master_doc,
"sphinxcontrib-mermaid",
"sphinxcontrib-mermaid documentation",
author,
"sphinxcontrib-mermaid",
"One line description of project.",
"Miscellaneous",
),
]
# Myst
myst_enable_extensions = ["amsmath", "colon_fence", "dollarmath", "html_image"]
myst_fence_as_directive = ["mermaid"]
mermaid_params = ["-ppuppeteer-config.json"]
mermaid_d3_zoom = True
mermaid_fullscreen = True
mermaid_include_elk = True
mermaid_include_mindmap = True
toctree_base = """{toctree}
---
caption: ""
maxdepth: 2
hidden: true
---"""
toctree_root = f"""```{toctree_base}
```
"""
def run_copyreadme(_):
out = Path("index.md")
readme = Path("../README.md")
out.write_text(toctree_root + "\n" + readme.read_text())
_GITHUB_ADMONITIONS = {
"> [!NOTE]": "note",
"> [!TIP]": "tip",
"> [!IMPORTANT]": "important",
"> [!WARNING]": "warning",
"> [!CAUTION]": "caution",
}
def run_convert_github_admonitions_to_rst(app, filename, lines):
# loop through lines, replace github admonitions
for i, orig_line in enumerate(lines):
orig_line_splits = orig_line.split("\n")
replacing = False
for j, line in enumerate(orig_line_splits):
# look for admonition key
for admonition_key in _GITHUB_ADMONITIONS:
if admonition_key in line:
line = line.replace(admonition_key, ":::{" + _GITHUB_ADMONITIONS[admonition_key] + "}\n")
# start replacing quotes in subsequent lines
replacing = True
break
else:
# replace indent to match directive
if replacing and "> " in line:
line = line.replace("> ", " ")
elif replacing:
# missing "> ", so stop replacing and terminate directive
line = f"\n:::\n{line}"
replacing = False
# swap line back in splits
orig_line_splits[j] = line
# swap line back in original
lines[i] = "\n".join(orig_line_splits)
def setup(app):
app.connect("builder-inited", run_copyreadme)
app.connect("source-read", run_convert_github_admonitions_to_rst)
sphinxcontrib-mermaid-2.0.0/docs/puppeteer-config.json 0000664 0000000 0000000 00000000037 15126273300 0023115 0 ustar 00root root 0000000 0000000 {
"args": ["--no-sandbox"]
}
sphinxcontrib-mermaid-2.0.0/docs/readme_pypa.md 0000664 0000000 0000000 00000001363 15126273300 0021561 0 ustar 00root root 0000000 0000000 # sphinxcontrib-mermaid
[](https://github.com/mgaitan/sphinxcontrib-mermaid/actions/workflows/test.yml)
[](https://pypi.org/project/sphinxcontrib-mermaid/)
[](https://libraries.io/pypi/sphinxcontrib-mermaid/)
This extension allows you to embed [Mermaid](https://mermaid.js.org/) graphs in your
documents, including general flowcharts, sequence diagrams, gantt diagrams and more.
See the [official Documentation](http://sphinxcontrib-mermaid-demo.readthedocs.io/en/latest/) or [project repository](https://github.com/mgaitan/sphinxcontrib-mermaid) for more details!
sphinxcontrib-mermaid-2.0.0/docs/requirements.txt 0000664 0000000 0000000 00000000037 15126273300 0022232 0 ustar 00root root 0000000 0000000 furo
myst-parser>=1.0.0
Sphinx
sphinxcontrib-mermaid-2.0.0/pyproject.toml 0000664 0000000 0000000 00000004242 15126273300 0020734 0 ustar 00root root 0000000 0000000 [build-system]
requires = ["setuptools"]
build-backend="setuptools.build_meta"
[project]
name = "sphinxcontrib-mermaid"
authors = [{name = "Martín Gaitán", email = "gaitan@gmail.com"}]
description="Mermaid diagrams in your Sphinx-powered docs"
readme = "docs/readme_pypa.md"
license = { text = "BSD" }
version = "2.0.0"
requires-python = ">=3.10"
keywords = ["sphinx", "mermaid", "diagrams", "documentation"]
classifiers = [
"Development Status :: 4 - Beta",
"Environment :: Console",
"Environment :: Web Environment",
"Framework :: Sphinx :: Extension",
"Intended Audience :: Developers",
"License :: OSI Approved :: BSD License",
"Operating System :: OS Independent",
"Programming Language :: Python :: Implementation :: CPython",
"Programming Language :: Python :: Implementation :: PyPy",
"Programming Language :: Python :: 3",
"Programming Language :: Python :: 3.10",
"Programming Language :: Python :: 3.11",
"Programming Language :: Python :: 3.12",
"Programming Language :: Python :: 3.13",
"Programming Language :: Python :: 3.14",
"Topic :: Documentation",
"Topic :: Utilities",
]
dependencies = [
"jinja2",
"sphinx",
"pyyaml",
]
[project.urls]
Repository = "https://github.com/mgaitan/sphinxcontrib-mermaid"
Homepage = "https://github.com/mgaitan/sphinxcontrib-mermaid"
Changelog = "https://github.com/mgaitan/sphinxcontrib-mermaid/blob/master/CHANGELOG.rst"
[project.optional-dependencies]
test = [
"defusedxml",
"myst-parser",
"pytest",
"ruff",
"sphinx"
]
[project.scripts]
[tool.pytest.ini_options]
asyncio_mode = "strict"
testpaths = "tests"
[tool.ruff]
line-length = 150
[tool.ruff.lint]
extend-select = ["I"]
[tool.ruff.lint.isort]
combine-as-imports = true
default-section = "third-party"
known-first-party = ["sphinxcontrib.mermaid"]
section-order = [
"future",
"standard-library",
"third-party",
"first-party",
"local-folder",
]
[tool.ruff.lint.per-file-ignores]
"__init__.py" = ["F401", "F403"]
[tool.setuptools.packages.find]
where = ["./"]
include = ["sphinxcontrib.mermaid"]
[tool.setuptools.package-data]
"sphinxcontrib.mermaid" = ["*.css", "*.js"]
sphinxcontrib-mermaid-2.0.0/sphinxcontrib/ 0000775 0000000 0000000 00000000000 15126273300 0020710 5 ustar 00root root 0000000 0000000 sphinxcontrib-mermaid-2.0.0/sphinxcontrib/mermaid/ 0000775 0000000 0000000 00000000000 15126273300 0022326 5 ustar 00root root 0000000 0000000 sphinxcontrib-mermaid-2.0.0/sphinxcontrib/mermaid/__init__.py 0000664 0000000 0000000 00000055043 15126273300 0024446 0 ustar 00root root 0000000 0000000 """
sphinx-mermaid
~~~~~~~~~~~~~~~
Allow mermaid diagrams to be included in Sphinx-generated
documents inline.
:copyright: Copyright 2016-2025 by Martín Gaitán and others
:license: BSD, see LICENSE for details.
"""
from __future__ import annotations
import codecs
import errno
import os
import posixpath
import re
import shlex
import uuid
from hashlib import sha1
from json import dumps, loads
from pathlib import Path
from subprocess import PIPE, Popen
from tempfile import TemporaryDirectory
import sphinx
from docutils import nodes
from docutils.parsers.rst import Directive, directives
from docutils.statemachine import ViewList
from jinja2 import Template
from packaging.version import Version
from sphinx.application import Sphinx
from sphinx.locale import _
from sphinx.util import logging
from sphinx.util.i18n import search_image_for_language
from sphinx.util.osutil import ensuredir
from yaml import dump
from .autoclassdiag import class_diagram
from .exceptions import MermaidError
logger = logging.getLogger(__name__)
# Load fullscreen CSS and JavaScript from external files
_MODULE_DIR = Path(__file__).parent
_FULLSCREEN_CSS = (_MODULE_DIR / "fullscreen.css.j2").read_text(encoding="utf-8")
_MERMAID_CSS = (_MODULE_DIR / "default.css.j2").read_text(encoding="utf-8")
_MERMAID_JS = (_MODULE_DIR / "default.js.j2").read_text(encoding="utf-8")
mapname_re = re.compile(r'
