MSC extension for Sphinx

Author:	LoveIsGrief <loveisgrief@tuta.io>

About

A fork of sphinxcontrib-mscgen This extension allows Mscgen-formatted :abbr:`MSC (Message Sequence Chart)` 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 :abbr:`MSC` descriptions and produces images as the output. :abbr:`MSC`s 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:

.. 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}";

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