sphinxcontrib-ditaa 0.2

1. Introduction

ditaa is a small command-line utility that can convert diagrams drawn using ascii art (‘drawings’ that contain characters that resemble lines like | / - ), into proper bitmap graphics. See http://ditaa.sourceforge.net/,

This extensions allows rendering of diagram using the ditaa to by included in Sphinx-generated. This extensions adds the ditaa directive that will replace the ascii diagram with the image of the ditaa.

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

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

You should convert and call it as:

ditaa art10.txt art10.png

If you don’t like the converttion, please refer to 4.2 Configuration for workaround. One possilbe convertation might be like this:

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

2. Installing and setup

pip install sphinxcontrib-ditaa

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

extensions = ['sphinxcontrib.ditaa']

3. Quick Example

This source:

.. ditaa::

    +--------+   +-------+    +-------+
    |        | --+ ditaa +--> |       |
    |  Text  |   +-------+    |diagram|
    |Document|   |!magic!|    |       |
    |     {d}|   |       |    |       |
    +---+----+   +-------+    +-------+
        :                         ^
        |       Lots of work      |
        +-------------------------+

is rendered as:

Another example:

.. ditaa::

    +----------+ edit +----------+   input +----------+ compile +----------+
    |  cPNK    |      |  cRED    |         |   cGRE   |         |  cPNK    |
    | refined  |<-----+ h,cpp    +-------->+ compiler,+-------->+Executable|
    |   h,cpp  |      |          |         | linker   |         |   File   |
    |          |      |          |         |          |         |          |
    +----------+      +----+-----+         +----------+         +----------+
                           | input
                           v
                      +----------+
                      |  cGRE    |
                      | doxygen  |
                      |          |
                      +----+-----+
                           | process
                           v
                      +----------+
                      |  cPNK    |
                      | Doxgen   |
                      | Document |
                      |          |
                      +----------+

is rendered as:

4. Usage

1. Firstly, make a directory and write the .rst files:

   $ mkdir test_dir
   $ cd test_dir
   $ vim test.rst

2) create a sphinex project in the directory, presss Enter if there is no change:

$ sphinx-quickstart

3) Just add sphinxcontrib.ditaa to the list of extensions in the conf.py file just created in step 2:

extensions = ['sphinxcontrib.ditaa']

4. Add your work .rst files into index.rst just created in step 2:

   Contents:
   
   .. toctree::
      :maxdepth: 2
   
      test.rst

5. make your target files:

   $ make html

or:

$ make pdf

6. check your target files:

   $ open .build/html/index.html

:--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:

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

.. 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     |
    \-------------+-------------/

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

5. License

GPLv3