././@PaxHeader0000000000000000000000000000003300000000000010211 xustar0027 mtime=1764035083.275846 sphinxcontrib_ditaa-1.0.3/0000755000175000017500000000000015111205013014664 5ustar00ypguoypguo././@PaxHeader0000000000000000000000000000002600000000000010213 xustar0022 mtime=1664117343.0 sphinxcontrib_ditaa-1.0.3/CHANGES0000644000175000017500000000014414314065137015675 0ustar00ypguoypguo.. -*- restructuredtext -*- Version 0.1 (2017-07-30) ------------------------ * Initial version. ././@PaxHeader0000000000000000000000000000002600000000000010213 xustar0022 mtime=1671248150.0 sphinxcontrib_ditaa-1.0.3/LICENSE0000644000175000017500000000256714347234426015727 0ustar00ypguoypguoIf 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. ././@PaxHeader0000000000000000000000000000002600000000000010213 xustar0022 mtime=1664117343.0 sphinxcontrib_ditaa-1.0.3/MANIFEST.in0000644000175000017500000000006314314065137016440 0ustar00ypguoypguoinclude README.rst include LICENSE include CHANGES ././@PaxHeader0000000000000000000000000000003400000000000010212 xustar0028 mtime=1764035083.2758229 sphinxcontrib_ditaa-1.0.3/PKG-INFO0000644000175000017500000001667315111205013015776 0ustar00ypguoypguoMetadata-Version: 2.4 Name: sphinxcontrib-ditaa Version: 1.0.3 Summary: Ditaa Sphinx extension. Home-page: https://github.com/stathissideris/ditaa Author: Yongping Guo Author-email: Yongping Guo License: BSD Keywords: sphinx,sphinxcontrib,ditaa Platform: any Description-Content-Type: text/x-rst License-File: LICENSE Dynamic: author Dynamic: home-page Dynamic: license-file Dynamic: platform 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, 10 Upgrade to formal release. 2) Fix a bug that ditaa doesn't work when ditaa options have values. 1.0.2 Fix some typo. 1.0.3 Use pyproject.toml to build. ././@PaxHeader0000000000000000000000000000002600000000000010213 xustar0022 mtime=1764034849.0 sphinxcontrib_ditaa-1.0.3/README.rst0000644000175000017500000001603315111204441016362 0ustar00ypguoypguosphinxcontrib-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, 10 Upgrade to formal release. 2) Fix a bug that ditaa doesn't work when ditaa options have values. 1.0.2 Fix some typo. 1.0.3 Use pyproject.toml to build. ././@PaxHeader0000000000000000000000000000002600000000000010213 xustar0022 mtime=1764034062.0 sphinxcontrib_ditaa-1.0.3/pyproject.toml0000640000175000017500000000104715111203016017577 0ustar00ypguoypguo[build-system] requires = ["setuptools", "wheel"] build-backend = "setuptools.build_meta" [project] name = "sphinxcontrib-ditaa" version = "1.0.3" authors = [ {name = "Yongping Guo", email = "guoyoooping@163.com"} ] description = "Ditaa Sphinx extension." keywords = ["sphinx", "sphinxcontrib", "ditaa"] readme = "README.rst" license = {text = "BSD"} dependencies = [ #"Pillow>=3.0.0", ] [tool.black] line-length = 88 target-version = ['py37'] [tool.isort] profile = "black" [tool.pytest.ini_options] minversion = "6.0" addopts = "-ra -q" ././@PaxHeader0000000000000000000000000000003400000000000010212 xustar0028 mtime=1764035083.2760816 sphinxcontrib_ditaa-1.0.3/setup.cfg0000644000175000017500000000004615111205013016505 0ustar00ypguoypguo[egg_info] tag_build = tag_date = 0 ././@PaxHeader0000000000000000000000000000002600000000000010213 xustar0022 mtime=1764034062.0 sphinxcontrib_ditaa-1.0.3/setup.py0000644000175000017500000000107415111203016016401 0ustar00ypguoypguo#!/usr/bin/env python from setuptools import setup, find_packages requires = ['Sphinx>=0.6', #'ditaa>=0.9', ] setup( name='sphinxcontrib-ditaa', version='1.0.3', 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'], ) ././@PaxHeader0000000000000000000000000000003400000000000010212 xustar0028 mtime=1764035083.2744772 sphinxcontrib_ditaa-1.0.3/sphinxcontrib/0000755000175000017500000000000015111205013017556 5ustar00ypguoypguo././@PaxHeader0000000000000000000000000000002600000000000010213 xustar0022 mtime=1664117343.0 sphinxcontrib_ditaa-1.0.3/sphinxcontrib/__init__.py0000644000175000017500000000055614314065137021714 0ustar00ypguoypguo# -*- 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__) ././@PaxHeader0000000000000000000000000000002600000000000010213 xustar0022 mtime=1671248150.0 sphinxcontrib_ditaa-1.0.3/sphinxcontrib/ditaa.py0000644000175000017500000001511114347234426021235 0ustar00ypguoypguo# -*- 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') ././@PaxHeader0000000000000000000000000000003400000000000010212 xustar0028 mtime=1764035083.2754219 sphinxcontrib_ditaa-1.0.3/sphinxcontrib_ditaa.egg-info/0000755000175000017500000000000015111205013022412 5ustar00ypguoypguo././@PaxHeader0000000000000000000000000000002600000000000010213 xustar0022 mtime=1764035083.0 sphinxcontrib_ditaa-1.0.3/sphinxcontrib_ditaa.egg-info/PKG-INFO0000644000175000017500000001667315111205013023524 0ustar00ypguoypguoMetadata-Version: 2.4 Name: sphinxcontrib-ditaa Version: 1.0.3 Summary: Ditaa Sphinx extension. Home-page: https://github.com/stathissideris/ditaa Author: Yongping Guo Author-email: Yongping Guo License: BSD Keywords: sphinx,sphinxcontrib,ditaa Platform: any Description-Content-Type: text/x-rst License-File: LICENSE Dynamic: author Dynamic: home-page Dynamic: license-file Dynamic: platform 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, 10 Upgrade to formal release. 2) Fix a bug that ditaa doesn't work when ditaa options have values. 1.0.2 Fix some typo. 1.0.3 Use pyproject.toml to build. ././@PaxHeader0000000000000000000000000000002600000000000010213 xustar0022 mtime=1764035083.0 sphinxcontrib_ditaa-1.0.3/sphinxcontrib_ditaa.egg-info/SOURCES.txt0000644000175000017500000000051715111205013024301 0ustar00ypguoypguoCHANGES LICENSE MANIFEST.in README.rst pyproject.toml 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/top_level.txt././@PaxHeader0000000000000000000000000000002600000000000010213 xustar0022 mtime=1764035083.0 sphinxcontrib_ditaa-1.0.3/sphinxcontrib_ditaa.egg-info/dependency_links.txt0000644000175000017500000000000115111205013026460 0ustar00ypguoypguo ././@PaxHeader0000000000000000000000000000002600000000000010213 xustar0022 mtime=1764035083.0 sphinxcontrib_ditaa-1.0.3/sphinxcontrib_ditaa.egg-info/namespace_packages.txt0000644000175000017500000000001615111205013026742 0ustar00ypguoypguosphinxcontrib ././@PaxHeader0000000000000000000000000000002600000000000010213 xustar0022 mtime=1764035083.0 sphinxcontrib_ditaa-1.0.3/sphinxcontrib_ditaa.egg-info/top_level.txt0000644000175000017500000000001615111205013025141 0ustar00ypguoypguosphinxcontrib