././@PaxHeader0000000000000000000000000000003400000000000011452 xustar000000000000000028 mtime=1671248252.5332177 sphinxcontrib-ditaa-1.0.2/0000755060175306017530000000000000000000000016037 5ustar00ypguoypguo00000000000000././@PaxHeader0000000000000000000000000000002600000000000011453 xustar000000000000000022 mtime=1664117343.0 sphinxcontrib-ditaa-1.0.2/CHANGES0000644060175306017530000000014400000000000017031 0ustar00ypguoypguo00000000000000.. -*- restructuredtext -*- Version 0.1 (2017-07-30) ------------------------ * Initial version. ././@PaxHeader0000000000000000000000000000002600000000000011453 xustar000000000000000022 mtime=1671247665.0 sphinxcontrib-ditaa-1.0.2/LICENSE0000644060175306017530000000256700000000000017056 0ustar00ypguoypguo00000000000000If not otherwise noted, the extensions in this package are licensed under the following license. Copyright (c) 2009 by the contributors. All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: * Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. ././@PaxHeader0000000000000000000000000000002600000000000011453 xustar000000000000000022 mtime=1664117343.0 sphinxcontrib-ditaa-1.0.2/MANIFEST.in0000644060175306017530000000006300000000000017574 0ustar00ypguoypguo00000000000000include README.rst include LICENSE include CHANGES ././@PaxHeader0000000000000000000000000000003400000000000011452 xustar000000000000000028 mtime=1671248252.5332177 sphinxcontrib-ditaa-1.0.2/PKG-INFO0000644060175306017530000002265400000000000017145 0ustar00ypguoypguo00000000000000Metadata-Version: 1.0 Name: sphinxcontrib-ditaa Version: 1.0.2 Summary: Ditaa Sphinx extension Home-page: https://github.com/stathissideris/ditaa Author: Yongping Guo Author-email: guoyoooping@163.com License: BSD Description: sphinxcontrib-ditaa ********************* :author: "Yongping Guo" 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`` : 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`` : Given a ditaa option list, default is empty. ``ditaa_log_enable`` : Since ditaa is slow, will give out a log to note progress if it's configured. Default is True. ditaa_output_suffix: : 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. Platform: any ././@PaxHeader0000000000000000000000000000002600000000000011453 xustar000000000000000022 mtime=1671247922.0 sphinxcontrib-ditaa-1.0.2/README.rst0000644060175306017530000001576200000000000017541 0ustar00ypguoypguo00000000000000sphinxcontrib-ditaa ********************* :author: "Yongping Guo" 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`` : 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`` : Given a ditaa option list, default is empty. ``ditaa_log_enable`` : Since ditaa is slow, will give out a log to note progress if it's configured. Default is True. ditaa_output_suffix: : 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. ././@PaxHeader0000000000000000000000000000003400000000000011452 xustar000000000000000028 mtime=1671248252.5332177 sphinxcontrib-ditaa-1.0.2/setup.cfg0000644060175306017530000000011400000000000017654 0ustar00ypguoypguo00000000000000[egg_info] tag_build = tag_date = 0 [aliases] release = egg_info -RDb '' ././@PaxHeader0000000000000000000000000000002600000000000011453 xustar000000000000000022 mtime=1671248072.0 sphinxcontrib-ditaa-1.0.2/setup.py0000644060175306017530000000107400000000000017553 0ustar00ypguoypguo00000000000000#!/usr/bin/env python from setuptools import setup, find_packages requires = ['Sphinx>=0.6', #'ditaa>=0.9', ] setup( name='sphinxcontrib-ditaa', version='1.0.2', url='https://github.com/stathissideris/ditaa', license='BSD', author='Yongping Guo', author_email='guoyoooping@163.com', description='Ditaa Sphinx extension', long_description=open('README.rst').read(), platforms='any', packages=find_packages(), include_package_data=True, install_requires=requires, namespace_packages=['sphinxcontrib'], ) ././@PaxHeader0000000000000000000000000000003200000000000011450 xustar000000000000000026 mtime=1671248252.52471 sphinxcontrib-ditaa-1.0.2/sphinxcontrib/0000755060175306017530000000000000000000000020731 5ustar00ypguoypguo00000000000000././@PaxHeader0000000000000000000000000000002600000000000011453 xustar000000000000000022 mtime=1671247822.0 sphinxcontrib-ditaa-1.0.2/sphinxcontrib/__init__.py0000644060175306017530000000055600000000000023050 0ustar00ypguoypguo00000000000000# -*- coding: utf-8 -*- """ sphinxcontrib ~~~~~~~~~~~~~ This package is a namespace package that contains all extensions distributed in the ``sphinx-contrib`` distribution. :copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS. :license: BSD, see LICENSE for details. """ __import__('pkg_resources').declare_namespace(__name__) ././@PaxHeader0000000000000000000000000000002600000000000011453 xustar000000000000000022 mtime=1671247502.0 sphinxcontrib-ditaa-1.0.2/sphinxcontrib/ditaa.py0000644060175306017530000001511100000000000022364 0ustar00ypguoypguo00000000000000# -*- coding: utf-8 -*- """ sphinxcontrib.ditaa ~~~~~~~~~~~~~~~~~~~~~ Allow ditaa commands be rendered as nice looking images See the README file for details. :author: Yongping Guo :license: BSD, see LICENSE for details Inspired by ``sphinxcontrib-aafig`` by Leandro Lucarella. """ import re, os import codecs import posixpath from os import path from math import ceil from subprocess import Popen, PIPE try: from hashlib import sha1 as sha except ImportError: from sha import sha from docutils import nodes from docutils.parsers.rst import directives from sphinx.errors import SphinxError from sphinx.util import ensuredir, relative_uri #from sphinx.util.compat import Directive def get_hashid(text,options): hashkey = text.encode('utf-8') + str(options).encode('utf-8') hashid = sha(hashkey).hexdigest() return hashid class DitaaError(SphinxError): category = 'ditaa error' class DitaaDirective(directives.images.Image): """ Directive that builds plots using ditaa. """ has_content = True required_arguments = 0 own_option_spec = dict( { '--no-antialias': str, '--background': str, '--no-separation': str, '--encoding': str, '--html': str, '--overwrite': str, '--round-corners': str, '--no-shadows': str, '--scale': str, '--transparent': str, '--tabs': str, '--fixed-slope': str, } ) option_spec = directives.images.Image.option_spec.copy() option_spec.update(own_option_spec) #print(option_spec) def run(self): self.arguments = [''] #print("self.options: %s" %(self.options)) ditaa_options = dict([(k,v) for k,v in self.options.items() if k in self.own_option_spec]) (image_node,) = directives.images.Image.run(self) if isinstance(image_node, nodes.system_message): return [image_node] text = '\n'.join(self.content) image_node.ditaa = dict(text=text,options=ditaa_options) return [image_node] def render_ditaa_images(app, doctree): #print("app.builder.env.docname: %s" %(app.builder.env.docname)) #print("app.builder.format: %s" %(app.builder.format)) #print(nodes) #print(dir(nodes)) for img in doctree.traverse(nodes.image): if not hasattr(img, 'ditaa'): continue text = img.ditaa['text'] options = img.ditaa['options'] try: relfn, outfn = render_ditaa(app, text, options, app.builder.format, "ditaa") img['uri'] = relfn except DitaaError: #app.builder.warn('ditaa error: ') img.replace_self(nodes.literal_block(text, text)) continue def render_ditaa(app, code, options, format, prefix='ditaa'): """Render ditaa code into a PNG output file.""" hashkey = code + str(options) + \ str(app.builder.config.ditaa) + \ str(app.builder.config.ditaa_args) hashkey = hashkey.encode('utf-8') infname = '%s-%s.%s' % (prefix, sha(hashkey).hexdigest(), "ditaa") outfname = '%s-%s.%s' % (prefix, sha(hashkey).hexdigest(), app.builder.config.ditaa_output_suffix) #rel_imgpath = (format == "html") and relative_uri(app.builder.env.docname, app.builder.imagedir) or '' if format == 'html': rel_imgpath = relative_uri(app.builder.env.docname, app.builder.imagedir) elif format == 'latex': rel_imgpath = relative_uri(app.builder.env.docname, app.builder.imagedir) else: app.builder.warn('gnuplot: the builder format %s is not officially supported.' % format) infullfn = path.join(app.builder.outdir, app.builder.imagedir, infname) outrelfn = posixpath.join(rel_imgpath, outfname) outfullfn = path.join(app.builder.outdir, app.builder.imagedir, outfname) #inrelfn = posixpath.join(relative_uri(app.builder.env.docname, app.builder.imagedir), infname) if path.isfile(outfullfn): return outrelfn, outfullfn ensuredir(path.dirname(outfullfn)) # ditaa expects UTF-8 by default #if isinstance(code, unicode): code = code.encode('utf-8') code = code.encode('utf-8') ditaa_args = [app.builder.config.ditaa] ditaa_args.extend(app.builder.config.ditaa_args) #print(options) for item in options.keys(): ditaa_args.append(item) if options[item] != "None": ditaa_args.append(options[item]) #ditaa_args.append(options) ditaa_args.extend( [infname, outfname] ) # use relative path f = open(infullfn, 'wb') f.write(code) f.close() currpath = os.getcwd() os.chdir(path.join(app.builder.outdir, app.builder.imagedir)) try: if app.builder.config.ditaa_log_enable: print("rending %s in %s.rst" %(outfullfn, app.builder.env.docname)) #app.builder.warn(ditaa_args) #print(ditaa_args) p = Popen(ditaa_args, stdout=PIPE, stdin=PIPE, stderr=PIPE) except OSError as err: if err.errno != ENOENT: # No such file or directory raise DitaaError("error") app.builder.warn('ditaa command %r cannot be run (needed for ditaa ' 'output), check the ditaa setting' % app.builder.config.ditaa) app.builder._ditaa_warned_dot = True os.chdir(currpath) return None, None os.chdir(currpath) wentWrong = False try: # Ditaa may close standard input when an error occurs, # resulting in a broken pipe on communicate() stdout, stderr = p.communicate(code) #print(stdout.decode("utf-8")) except OSError as err: if err.errno != EPIPE: raise DitaaError("error") wentWrong = True except IOError as err: if err.errno != EINVAL: raise DitaaError("error") wentWrong = True if wentWrong: # in this case, read the standard output and standard error streams # directly, to get the error message(s) stdout, stderr = p.stdout.read(), p.stderr.read() p.wait() if p.returncode != 0: raise DitaaError('ditaa exited with error:\n[stderr]\n%s\n' '[stdout]\n%s' % (stderr, stdout)) return outrelfn, outfullfn def setup(app): app.add_directive('ditaa', DitaaDirective) app.connect('doctree-read', render_ditaa_images) app.add_config_value('ditaa', 'ditaa', 'html') app.add_config_value('ditaa_args', [], 'html') app.add_config_value('ditaa_output_suffix', 'png', 'html') app.add_config_value('ditaa_log_enable', True, 'html') ././@PaxHeader0000000000000000000000000000003400000000000011452 xustar000000000000000028 mtime=1671248252.5332177 sphinxcontrib-ditaa-1.0.2/sphinxcontrib_ditaa.egg-info/0000755060175306017530000000000000000000000023565 5ustar00ypguoypguo00000000000000././@PaxHeader0000000000000000000000000000002600000000000011453 xustar000000000000000022 mtime=1671248252.0 sphinxcontrib-ditaa-1.0.2/sphinxcontrib_ditaa.egg-info/PKG-INFO0000644060175306017530000002265400000000000024673 0ustar00ypguoypguo00000000000000Metadata-Version: 1.0 Name: sphinxcontrib-ditaa Version: 1.0.2 Summary: Ditaa Sphinx extension Home-page: https://github.com/stathissideris/ditaa Author: Yongping Guo Author-email: guoyoooping@163.com License: BSD Description: sphinxcontrib-ditaa ********************* :author: "Yongping Guo" 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`` : 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`` : Given a ditaa option list, default is empty. ``ditaa_log_enable`` : Since ditaa is slow, will give out a log to note progress if it's configured. Default is True. ditaa_output_suffix: : 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. Platform: any ././@PaxHeader0000000000000000000000000000002600000000000011453 xustar000000000000000022 mtime=1671248252.0 sphinxcontrib-ditaa-1.0.2/sphinxcontrib_ditaa.egg-info/SOURCES.txt0000644060175306017530000000056400000000000025456 0ustar00ypguoypguo00000000000000CHANGES LICENSE MANIFEST.in README.rst setup.cfg setup.py sphinxcontrib/__init__.py sphinxcontrib/ditaa.py sphinxcontrib_ditaa.egg-info/PKG-INFO sphinxcontrib_ditaa.egg-info/SOURCES.txt sphinxcontrib_ditaa.egg-info/dependency_links.txt sphinxcontrib_ditaa.egg-info/namespace_packages.txt sphinxcontrib_ditaa.egg-info/requires.txt sphinxcontrib_ditaa.egg-info/top_level.txt././@PaxHeader0000000000000000000000000000002600000000000011453 xustar000000000000000022 mtime=1671248252.0 sphinxcontrib-ditaa-1.0.2/sphinxcontrib_ditaa.egg-info/dependency_links.txt0000644060175306017530000000000100000000000027633 0ustar00ypguoypguo00000000000000 ././@PaxHeader0000000000000000000000000000002600000000000011453 xustar000000000000000022 mtime=1671248252.0 sphinxcontrib-ditaa-1.0.2/sphinxcontrib_ditaa.egg-info/namespace_packages.txt0000644060175306017530000000001600000000000030115 0ustar00ypguoypguo00000000000000sphinxcontrib ././@PaxHeader0000000000000000000000000000002600000000000011453 xustar000000000000000022 mtime=1671248252.0 sphinxcontrib-ditaa-1.0.2/sphinxcontrib_ditaa.egg-info/requires.txt0000644060175306017530000000001400000000000026160 0ustar00ypguoypguo00000000000000Sphinx>=0.6 ././@PaxHeader0000000000000000000000000000002600000000000011453 xustar000000000000000022 mtime=1671248252.0 sphinxcontrib-ditaa-1.0.2/sphinxcontrib_ditaa.egg-info/top_level.txt0000644060175306017530000000001600000000000026314 0ustar00ypguoypguo00000000000000sphinxcontrib