MSC extension for Sphinx¶

author: LoveIsGrief <loveisgrief@tuta.io>

About¶

A fork of sphinxcontrib-mscgen This extension allows Mscgen-formatted MSC diagrams to be included in Sphinx-generated HTML documents inline. It also supports JSON, MsGenny, and Xu.

Mscgen is a small program (inspired by Graphviz Dot) that parses MSC descriptions and produces images as the output. MSCs are a way of representing entities and interactions over some time period, very similar to UML sequence diagrams.

MscgenJS is a reimplementation of thaat using JS as a CLI tool and embeddable on websites, the latter of which this extension takes advantage of.

You can see the latest documentation at the sphinxcontrib-mscgenjs website.

Quick Example¶

This source:

.. mscgenjs::
     :language: msgenny

     # OpenId Connect protocol
     # https://openid.net/specs/openid-connect-core-1_0.html#rfc.section.1.3
     wordwraparcs=true;

     eu : "end-user",
     rp : "relying party",
     op : "OpenID provider";

     eu =>> rp : "log me in";
     rp =>> op : "authentication request";
     op =>> eu : "authentication and authorization request";
     eu >> op : "authenticate and authorize";
     op >> rp : "authentication response";
     rp =>> op : "UserInfo request";
     op >> rp : "UserInfo response";
     rp >> eu : "Hi. You're logged in with {UserInfo.name}";

is rendered as:

# OpenId Connect protocol # https://openid.net/specs/openid-connect-core-1_0.html#rfc.section.1.3 wordwraparcs=true; eu : "end-user", rp : "relying party", op : "OpenID provider"; eu =>> rp : "log me in"; rp =>> op : "authentication request"; op =>> eu : "authentication and authorization request"; eu >> op : "authenticate and authorize"; op >> rp : "authentication response"; rp =>> op : "UserInfo request"; op >> rp : "UserInfo response"; rp >> eu : "Hi. You're logged in with {UserInfo.name}";

Download¶

You can see all the available versions at PyPI.

Install¶

From source (tar.gz or checkout)¶

Unpack the archive, enter the sphinxcontrib-mscgenjs-x.y directory and run:

python setup.py install

Setuptools/PyPI ¶

Alternatively it can be installed from PyPI, either manually downloading the files and installing as described above or using:

pip install -U sphinxcontrib-mscgenjs

Enabling the extension in Sphinx ¶

Just add sphinxcontrib.mscgenjs to the list of extensions in the conf.py file. For example:

extensions = ['sphinxcontrib.mscgenjs']

Usage¶

This extension adds the mscgenjs directive. Using the :language: option with json, msgenny or xu different formats can be chosen.

For an example on using the mscgenjs directive see the Quick Example.

Remember to enable the extension first (see Install for details).

ChangeLog¶

This file describes user-visible changes between the extension versions.

Version 0.1.4¶

Use <div> instead of <pre> due to sphinx styling

Version 0.1.3¶

Just a version bump due to problem while building package. It included an old source file (sphinxcontrib/mscgenjs.py) that had been moved to a new location (sphinxcontrib/mscgenjs/__init__.py)

Version 0.1.2¶

Actually include mscgen-inpage.js (it’s now in a new place)

Version 0.1.1¶

Attempt to fix importing mscgen-inpage.js after install from PyPi

Version 0.1¶

Fork from https://github.com/sphinx-contrib/mscgen
Initial version.

License¶

I don't like licenses, because I don't like having to worry about all this
legal stuff just for a simple piece of software I don't really mind anyone
using. But I also believe that it's important that people share and give back;
so I'm placing this work under the following license.


BOLA - Buena Onda License Agreement (v1.0)
------------------------------------------

This work is provided 'as-is', without any express or implied warranty. In no
event will the authors be held liable for any damages arising from the use of
this work.

To all effects and purposes, this work is to be considered Public Domain.


However, if you want to be "buena onda", you should:

1. Not take credit for it, and give proper recognition to the authors.
2. Share your modifications, so everybody benefits from them.
3. Do something nice for the authors.
4. Help someone who needs it.
5. Don't waste. Anything, but specially energy that comes from natural
   non-renewable resources.
6. Be tolerant. Everything that's good in nature comes from cooperation.