sphinxcontrib-ditaa 1.0.3

2.1 prerequisite

ditaa is in java, normally it’s call by the following format:

java -jar /usr/local/Cellar/ditaa/0.10/libexec/ditaa0_10.jar art10.txt art10.png

to use it in the sphinx we should convert it to a single command and call it as:

ditaa art10.txt art10.png

There are two means to do that:

1. Crate a execuable script as following:

   $ cat /usr/local/bin/ditaa
   #!/bin/bash
   exec java  -jar /usr/local/Cellar/ditaa/0.10/libexec/ditaa0_10.jar "$@"

2. If you don’t like the converttion, please refer to 2.3 Configuration for the workaround. you can add the following configuration to the conf.py:

   ditaa = "java"
   ditaa_args = ["-jar", "/usr/local/Cellar/ditaa/0.10/libexec/ditaa0_10.jar"]
   ditaa_log_enable = True

2.2 install sphinxcontrib-ditaa

pip install sphinxcontrib-ditaa

2.3 configuration

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

extensions = ['sphinxcontrib.ditaa']

sphinxcontrib-ditaa also provide configuration to add different options to ditaa command and render different kind of output:

ditaa <str>:

Ditaa is a java implementation and maybe is not callable directly, please input the ditaa executale name if you didn’t convert it to a normal command. Default is “ditaa”. See examples below.

ditaa_args <list>:

Given a ditaa option list, default is empty.

ditaa_log_enable <Bool>:

Since ditaa is slow, will give out a log to note progress if it’s configured. Default is True.

ditaa_output_suffix: <str>:

The output file format.

For example:

ditaa = "java"
ditaa_args = ["-jar", "/usr/local/Cellar/ditaa/0.10/libexec/ditaa0_10.jar"]
ditaa_log_enable = True

4.1 Options

1. ditaa options:

See detail in ditaa -h:

:--no-antialias:
:--background:
:--no-antialias:
:--no-separation:
:--encoding:
:--html:
:--overwrite:
:--round-corners:
:--no-shadows:
:--scale: 1.5 #Please note that it's ditaa's parameter and the units are
           fractions of the default size (2.5 renders 1.5 times bigger
           than the default). Be warning to be different from image's
           scale unit.
:--transparent:
:--tabs:
:--fixed-slope:

2. image options:

See detail in rst syntax:

:name:
:class:
:alt:
:title:
:height:
:width:
:scale: 50%, Please node that it's integer percentage (the "%" symbol is optional)
:align:
:target:
:inline:

Examples:

.. ditaa::
   :--no-antialias:
   :--transparent:
   :--scale: 1.5
   :alt: a test for ditaa.
   :width: 600
   :height: 400
   :align: left
   :scale: 50

    Color codes
    /-------------+-------------\
    |cRED RED     |cBLU BLU     |
    +-------------+-------------+
    |cGRE GRE     |cPNK PNK     |
    +-------------+-------------+
    |cBLK BLK     |cYEL YEL     |
    \-------------+-------------/