MSC extension for Sphinx

author:Leandro Lucarella <llucax@gmail.com>

About

This extension allow Mscgen-formatted MSC diagrams to be included in Sphinx-generated documents inline.

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.

You can see the latest documentation at the sphinxcontrib-mscgen website or download it in PDF format.

Quick Example

This source:

.. msc::

   hscale = "0.5";

   a,b,c;

   a->b [ label = "ab()" ] ;
   b->c [ label = "bc(TRUE)"];
   c=>c [ label = "process()" ];

is rendered as:

Download

You can see all the available versions at PyPI.

Install

Requirements

• mscgen (0.14 or later).
• epstopdf for LaTeX/PDF output.

From source (tar.gz or checkout)

Unpack the archive, enter the sphinxcontrib-mscgen-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:

easy_install -U sphinxcontrib-mscgen

Enabling the extension in Sphinx

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

extensions = ['sphinxcontrib.mscgen']

Usage

The Mscgen program is used to render the MSC, so you should refer to its documentation for details on how to specify the diagram. You should have the program installed for this extension to work. If you need LaTeX output, you’ll need the epstopdf program too.

This extension adds the mscgen and msc directives. The former let you specify a full diagram, the later let you omit the msc { ... } bits so you can jump right to the important stuff.

For an example on using the msc directive see the Quick Example. If you need full control over the MSC diagram you can use the mscgen directive:

.. mscgen::

   msc {
      hscale = "0.5";

      a,b,c;

      a->b [ label = "ab()" ] ;
      b->c [ label = "bc(TRUE)"];
      c=>c [ label = "process()" ];
   }

Which renders to exact the same image as the Quick Example.

Configuration

A few configuration options are added (all optional, of course ;) to Sphinx so you can set them in the conf.py file:

mscgen:

location of the mscgen program. It’s expected to be in the PATH by default. The full path, including the binary, should be given if that’s not the case.

mscgen_args:

extra command line arguments for mscgen (should be a list of strings).

mscgen_epstopdf:

location of the epstopdf program. It’s expected to be in the PATH by default. The full path, including the binary, should be given if that’s not the case.

mscgen_epstopdf_args:

extra command line arguments for epstopdf (should be a list of strings).

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

ChangeLog

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

Version 0.4 (2009-11-21)

• Add website.
• Change license to BOLA.
• Minor code cleanups.

Version 0.3 (2009-06-05)

• Fix a bug when exposed when epstopdf fails.
• Add [] to \includegraphics in LaTeX output so it can be centered in figures using \centering.
• Improve documentation.

Version 0.2 (unreleased)

• Add image maps support for HTML output.

Version 0.1 (unreleased)

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