sphinxcontrib-ditaa
*********************
:author: "Yongping Guo"<guoyoooping@163.com>
A sphinx extension for embedding block diagram using ditaa.
This extension enables you to insert block diagrams into your document generated by sphinx. Following code is an example::
.. ditaa::
+--------+ +-------+ +-------+
| | --+ ditaa +--> | |
| Text | +-------+ |diagram|
|Document| |!magic!| | |
| {d}| | | | |
+---+----+ +-------+ +-------+
: ^
| Lots of work |
+-------------------------+
After conversion using ditaa, the above file becomes:
.. image:: http://ditaa.sourceforge.net/images/first.png
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/.
ditaa_ is a java programme and the input must be a plain text file and the output is a seperate image file. It's inconvenient for user to include the image directly. This extensions allows the plain-text graph in .rst file to be rendered as a graph drawn by ditaa_ in sphinx scheme. With this plugin you can focus the graph itself and the ditaa and sphinx would convert it automatically.
Now it support to render the image into html and pdf target.
2. Install and configuration
============================
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
3. Quick Example
================
This source::
.. ditaa::
+--------+ +-------+ +-------+
| | --+ ditaa +--> | |
| Text | +-------+ |diagram|
|Document| |!magic!| | |
| {d}| | | | |
+---+----+ +-------+ +-------+
: ^
| Lots of work |
+-------------------------+
is rendered as:
.. image:: http://ditaa.sourceforge.net/images/first.png
Another example::
.. ditaa::
+----------+
Drawing with |cYEL {s}|
ditaa + +
| emacs fu |
+----------+
^
|
+--------+ +-------+ +-------+
|cGRE |-->+ ditaa +--> | |
| Text | +-------+ |diagram|
|Document| | magic!| | |
| {d}| |cBLU | | cRED |
+---+----+ +-------+ +-------+
^
|
+--------+
|cPNK{io}|
| user |
+--------+
is rendered as:
.. image:: http://1.bp.blogspot.com/_kGFGcbwevHE/SYDL362PTdI/AAAAAAAAAXQ/VaK15NeJUWQ/s1600/test_11.png
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
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 |
\-------------+-------------/
5. License
==========
GPLv3
.. _ditaa: http://ditaa.sourceforge.net/
.. _Sphinx: http://sphinx.pocoo.org/
6. Changelog
============
0.5
Don't import sphinx.util.compat since sphinx.util.compat is deprecated at 1.6
and is removed since Sphinx 1.7.
0.6
Support python3
1.0
upgrade to formal release.
Fix a bug that ditaa doesn't work when ditaa options have values.
1.0.2
Fix some typo.
Raw data
{
"_id": null,
"home_page": "https://github.com/stathissideris/ditaa",
"name": "sphinxcontrib-ditaa",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "",
"author": "Yongping Guo",
"author_email": "guoyoooping@163.com",
"download_url": "https://files.pythonhosted.org/packages/d7/8f/7246e4c341998de33ca3e23729d85548aeae12af6da817d437cbbb29640d/sphinxcontrib-ditaa-1.0.2.tar.gz",
"platform": "any",
"description": "sphinxcontrib-ditaa\n*********************\n\n:author: \"Yongping Guo\"<guoyoooping@163.com>\n\nA sphinx extension for embedding block diagram using ditaa.\n\nThis extension enables you to insert block diagrams into your document generated by sphinx. Following code is an example::\n\n .. ditaa::\n\n +--------+ +-------+ +-------+\n | | --+ ditaa +--> | |\n | Text | +-------+ |diagram|\n |Document| |!magic!| | |\n | {d}| | | | |\n +---+----+ +-------+ +-------+\n : ^\n | Lots of work |\n +-------------------------+\n\nAfter conversion using ditaa, the above file becomes:\n\n.. image:: http://ditaa.sourceforge.net/images/first.png\n\n1. Introduction\n===============\n\nditaa_ 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/.\n\nditaa_ is a java programme and the input must be a plain text file and the output is a seperate image file. It's inconvenient for user to include the image directly. This extensions allows the plain-text graph in .rst file to be rendered as a graph drawn by ditaa_ in sphinx scheme. With this plugin you can focus the graph itself and the ditaa and sphinx would convert it automatically.\n\nNow it support to render the image into html and pdf target.\n\n2. Install and configuration\n============================\n\n2.1 prerequisite\n----------------\n\nditaa_ is in java, normally it's call by the following format::\n\n java -jar /usr/local/Cellar/ditaa/0.10/libexec/ditaa0_10.jar art10.txt art10.png \n\nto use it in the sphinx we should convert it to a single command and call it as::\n\n ditaa art10.txt art10.png \n\nThere are two means to do that:\n\n1) Crate a execuable script as following::\n\n $ cat /usr/local/bin/ditaa\n #!/bin/bash\n exec java -jar /usr/local/Cellar/ditaa/0.10/libexec/ditaa0_10.jar \"$@\"\n\n2) 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::\n\n ditaa = \"java\"\n ditaa_args = [\"-jar\", \"/usr/local/Cellar/ditaa/0.10/libexec/ditaa0_10.jar\"]\n ditaa_log_enable = True\n\n2.2 install sphinxcontrib-ditaa\n-------------------------------\n\n::\n\n pip install sphinxcontrib-ditaa\n\n2.3 configuration\n-----------------\n\nJust add ``sphinxcontrib.ditaa`` to the list of extensions in the ``conf.py`` file. For example::\n\n extensions = ['sphinxcontrib.ditaa']\n\nsphinxcontrib-ditaa also provide configuration to add different options to ditaa command and render different kind of output:\n\n``ditaa`` <str>:\n\n Ditaa is a java implementation and maybe is not callable directly, please\n input the ditaa executale name if you didn't convert it to a normal\n command. Default is \"ditaa\". See examples below.\n\n``ditaa_args`` <list>:\n\n Given a ditaa option list, default is empty.\n\n``ditaa_log_enable`` <Bool>:\n\n Since ditaa is slow, will give out a log to note progress if it's\n configured. Default is True.\n\nditaa_output_suffix: <str>:\n\n The output file format.\n\nFor example::\n\n ditaa = \"java\"\n ditaa_args = [\"-jar\", \"/usr/local/Cellar/ditaa/0.10/libexec/ditaa0_10.jar\"]\n ditaa_log_enable = True\n\n3. Quick Example\n================\n\nThis source::\n\n .. ditaa::\n\n +--------+ +-------+ +-------+\n | | --+ ditaa +--> | |\n | Text | +-------+ |diagram|\n |Document| |!magic!| | |\n | {d}| | | | |\n +---+----+ +-------+ +-------+\n : ^\n | Lots of work |\n +-------------------------+\n\nis rendered as:\n\n.. image:: http://ditaa.sourceforge.net/images/first.png\n\nAnother example::\n\n .. ditaa::\n\n +----------+\n Drawing with |cYEL {s}|\n ditaa + +\n | emacs fu |\n +----------+\n ^ \n | \n +--------+ +-------+ +-------+ \n |cGRE |-->+ ditaa +--> | | \n | Text | +-------+ |diagram| \n |Document| | magic!| | | \n | {d}| |cBLU | | cRED | \n +---+----+ +-------+ +-------+ \n ^ \n |\n +--------+\n |cPNK{io}| \n | user |\n +--------+\n\nis rendered as:\n\n.. image:: http://1.bp.blogspot.com/_kGFGcbwevHE/SYDL362PTdI/AAAAAAAAAXQ/VaK15NeJUWQ/s1600/test_11.png\n\n4. Usage\n========\n\n1) Firstly, make a directory and write the .rst files::\n\n $ mkdir test_dir\n $ cd test_dir\n $ vim test.rst\n\n2) create a sphinex project in the directory, presss Enter if there is no\nchange::\n\n $ sphinx-quickstart\n\n3) Just add ``sphinxcontrib.ditaa`` to the list of extensions in the\n``conf.py`` file just created in step 2::\n\n extensions = ['sphinxcontrib.ditaa']\n\n4) Add your work .rst files into index.rst just created in step 2::\n\n Contents:\n \u00a0\n .. toctree::\n \u00a0\u00a0\u00a0:maxdepth: 2\n \u00a0\n \u00a0\u00a0\u00a0test.rst\n\n5) make your target files::\n\n $ make html\n\nor::\n\n $ make pdf\n\n6) check your target files:\n\n $ open .build/html/index.html\n\n4.1 Options\n-----------\n\n1) ditaa options:\n\nSee detail in ditaa -h::\n\n :--no-antialias:\n :--background:\n :--no-antialias:\n :--no-separation:\n :--encoding:\n :--html:\n :--overwrite:\n :--round-corners:\n :--no-shadows:\n :--scale: 1.5 #Please note that it's ditaa's parameter and the units are\n fractions of the default size (2.5 renders 1.5 times bigger\n than the default). Be warning to be different from image's\n scale unit.\n :--transparent:\n :--tabs:\n :--fixed-slope:\n\n2) image options:\n\nSee detail in rst syntax::\n\n :name: \n :class: \n :alt: \n :title:\n :height: \n :width: \n :scale: 50%, Please node that it's integer percentage (the \"%\" symbol is optional)\n :align: \n :target: \n :inline: \n\nExamples::\n\n .. ditaa::\n :--no-antialias:\n :--transparent: \n :--scale: 1.5\n :alt: a test for ditaa.\n :width: 600\n :height: 400\n :align: left\n :scale: 50\n\n Color codes\n /-------------+-------------\\\n |cRED RED |cBLU BLU |\n +-------------+-------------+\n |cGRE GRE |cPNK PNK |\n +-------------+-------------+\n |cBLK BLK |cYEL YEL |\n \\-------------+-------------/\n\n5. License\n==========\n\nGPLv3\n\n.. _ditaa: http://ditaa.sourceforge.net/\n.. _Sphinx: http://sphinx.pocoo.org/\n\n6. Changelog\n============\n\n0.5\n\nDon't import sphinx.util.compat since sphinx.util.compat is deprecated at 1.6\nand is removed since Sphinx 1.7.\n\n\n0.6\n\nSupport python3\n\n1.0\n\nupgrade to formal release.\nFix a bug that ditaa doesn't work when ditaa options have values.\n\n1.0.2\n\nFix some typo.",
"bugtrack_url": null,
"license": "BSD",
"summary": "Ditaa Sphinx extension",
"version": "1.0.2",
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"md5": "5a0fb8d39f8fb183377578d9c0b71e7b",
"sha256": "57f2e13b059b38fde89580beca916ac6ca7456b2d706c3ddea9dd4890e5f5bd3"
},
"downloads": -1,
"filename": "sphinxcontrib-ditaa-1.0.2.tar.gz",
"has_sig": false,
"md5_digest": "5a0fb8d39f8fb183377578d9c0b71e7b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 8553,
"upload_time": "2022-12-17T03:38:13",
"upload_time_iso_8601": "2022-12-17T03:38:13.932793Z",
"url": "https://files.pythonhosted.org/packages/d7/8f/7246e4c341998de33ca3e23729d85548aeae12af6da817d437cbbb29640d/sphinxcontrib-ditaa-1.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2022-12-17 03:38:13",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "stathissideris",
"github_project": "ditaa",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "sphinxcontrib-ditaa"
}
JSON
