Kirill Simonov avatar Kirill Simonov committed faa41e0

Renamed teximage -> texfigure; updated documentation.

Comments (0)

Files changed (8)

 
-include README NEWS LICENSE demo/Makefile demo/conf.py demo/*.rst demo/*.tex
+include README LICENSE demo/Makefile demo/conf.py demo/*.rst demo/*.tex
 

NEWS

-List of Changes
-===============
-
-
-0.1 (2013-XX-XX)
-----------------
-
-* Initial release.
-
-
-****************************************************************
-  ``sphinxcontrib-teximage`` -- TeX Image extension for Sphinx
-****************************************************************
+******************************************************************
+  ``sphinxcontrib-texfigure`` -- TeX Figure extension for Sphinx
+******************************************************************
 
 Overview
 ========
 
-``sphinxcontrib-teximage`` is an extension for generating diagrams
-from TeX documents and embedding them into Sphinx_ documents.
+``sphinxcontrib-texfigure`` is an extension for generating figures and
+diagrams from TeX files and embedding them into Sphinx_ documents.
 
 For an example of a diagram this extension could produce, please see
 http://htsql.org/doc/overview.html#htsql-in-a-nutshell
 Prerequisites
 =============
 
-To convert a TeX document to a raster image, the extension uses the
-following executables::
+The following executables are used for rasterizing TeX documents:
 
 * ``pdflatex``
 * ``pdftoppm``
 * ``pnmcrop``
 * ``pnmtopng``
 
-On a Debian_ or `Debian-derived`_ system, they could be installed with::
+On a Debian_ or a `Debian-derived`_ system, they could be installed
+with::
 
     # apt-get install texlive
     # apt-get install poppler-utils
     # apt-get install netpbm
 
-If you want to generate diagrams using TikZ_, install::
+If you want to generate diagrams with TikZ_, install::
 
     # apt-get install texlive-pictures
 
 
 To enable this extension, add the following line to ``conf.py``::
 
-    extensions.append('sphinxcontrib.teximage')
+    extensions.append('sphinxcontrib.texfigure')
 
-To render an image from a TeX document, use ``teximage`` directive::
+Use ``texfigure`` directive to convert a TeX/LaTeX document to an image.
+For example::
 
-    .. teximage:: diagram.tex
+    .. texfigure:: hello-world.tex
 
-Place the file ``diagram.tex`` in the same directory.  It must contain
-a valid TeX/LaTeX document.  For example::
+This directive will render *Hello, World!* in a box assuming that
+``hello-world.tex`` contains the following LaTeX document::
 
-    \documentclass{article}
+       \documentclass{article}
+       \usepackage{tikz}
+       \pagestyle{empty}
 
-    \usepackage{tikz}
-    \pagestyle{empty}
+       \begin{document}
+       \begin{tikzpicture}
+       \node[draw] {Hello, World!};
+       \end{tikzpicture}
+       \end{document}
 
-    \begin{document}
+Use option ``align`` to specify horizontal alignment, ``alt`` to specify
+text content of the image::
 
-    \begin{tikzpicture}
-    \node[draw] {Hello, World!};
-    \end{tikzpicture}
-
-    \end{document}
+    .. texfigure:: hello-world.tex
+       :align: center
+       :alt: Hello, World!
 
 
 Reference
 Directives
 ----------
 
-``teximage``
+``texfigure``
     Renders an image from a TeX document.
 
+    The parameter of the directive must be the path to a TeX/LaTeX file.
+    This directive has no body.
+
     Options:
 
     ``align``
-        Image alignment (``left``, ``center``, or ``right``)
-
+        Horizontal alignment (``left``, ``center``, or ``right``)
     ``alt``
-        Image alternative text.
+        Alternative text content of the image.
 
 Configuration parameters
 ------------------------
 
-``teximage_pdftex`` (default: ``pdflatex``)
+``texfigure_pdftex`` (default: ``pdflatex``)
     Path to ``pdftex`` or ``pdflatex`` executable.
 
-``teximage_pdftoppm`` (default: ``pdftoppm``)
+``texfigure_pdftoppm`` (default: ``pdftoppm``)
     Path to ``pdftoppm`` executable.
 
-``teximage_pnmcrop`` (default: ``pnmcrop``)
+``texfigure_pnmcrop`` (default: ``pnmcrop``)
     Path to ``pnmcrop`` executable.
 
-``teximage_pnmtopng`` (default: ``pnmtopng``)
+``texfigure_pnmtopng`` (default: ``pnmtopng``)
     Path to ``pnmtopng`` executable.
 
-``teximage_texinputs`` (default: ``[]``)
+``texfigure_texinputs`` (default: ``[]``)
     List of directories where TeX searches for input files.
 
-``teximage_resolution`` (default: ``110``)
+``texfigure_resolution`` (default: ``110``)
     Image resolution, in DPI.
 
 CSS classes
 -----------
 
-``teximage``
+``texfigure``
     Wraps the generated image.
 
 
 
-# Enable `sphinxcontrib-teximage` extension.
-extensions = ['sphinxcontrib.teximage']
+# Enable `sphinxcontrib-texfigure` extension.
+extensions = ['sphinxcontrib.texfigure']
 
 # Standard configuration.
 project = u'A Project with Diagrams'
 Diagram Examples
 ================
 
-This document shows how to include diagrams with ``sphinxcontrib-teximage``
-extensions.
+This document shows how to generate figures and diagrams with
+``sphinxcontrib-texfigure`` extension.
 
 Hello, World!
 -------------
 
+.. texfigure:: hello-world.tex
+
+This image is rendered using ``texfigure`` directive:
+
 .. sourcecode:: rst
 
-   .. teximage:: hello-world.tex
+   .. texfigure:: hello-world.tex
+
+File ``hello-world.tex`` contains the following LaTeX document:
 
 .. literalinclude:: hello-world.tex
 
-.. teximage:: hello-world.tex
-
 Database Schema
 ---------------
 
+.. texfigure:: database-schema.tex
+   :align: center
+   :alt: Database schema for HTSQL regression tests
+
+This diagram was rendered using the following directive:
+
 .. sourcecode:: rst
 
-   .. teximage:: database-schema.tex
+   .. texfigure:: database-schema.tex
       :align: center
+      :alt: Database schema for HTSQL regression tests
 
-.. teximage:: database-schema.tex
-   :align: center
+The LaTeX document is split into two files.  File ``preamble.tex`` contains
+common definitions:
 
 .. literalinclude:: preamble.tex
 
+File ``database-schema.tex`` contains the diagram itself:
+
 .. literalinclude:: database-schema.tex
 
 from setuptools import setup
 
 
-NAME = "sphinxcontrib-teximage"
+NAME = "sphinxcontrib-texfigure"
 VERSION = "0.1"
-DESCRIPTION = "TeX Image extension for Sphinx"
+DESCRIPTION = "TeX Figure extension for Sphinx"
 LONG_DESCRIPTION = open('README').read()
 AUTHOR = "Kirill Simonov (Prometheus Research, LLC)"
 AUTHOR_EMAIL = "xi@resolvent.net"
 LICENSE = "BSD"
-URL = "http://bitbucket.org/prometheus/sphinxcontrib-teximage"
-DOWNLOAD_URL = "http://pypi.python.org/pypi/sphinxcontrib-teximage"
+URL = "http://bitbucket.org/prometheus/sphinxcontrib-texfigure"
+DOWNLOAD_URL = "http://pypi.python.org/pypi/sphinxcontrib-texfigure"
 CLASSIFIERS = [
         'Development Status :: 4 - Beta',
         'Intended Audience :: Developers',

sphinxcontrib/texfigure.py

+#
+# Copyright (c) 2013, Prometheus Research, LLC
+#
+
+
+from docutils import nodes
+from docutils.parsers.rst import Directive, directives
+from sphinx.util.osutil import ensuredir
+from subprocess import Popen, PIPE
+import os, os.path, tempfile, shutil
+
+
+class TeXFigureDirective(Directive):
+
+    required_arguments = 1
+    has_content = False
+    option_spec = {
+        'alt': directives.unchanged,
+        'align': lambda arg: directives.choice(arg, ('left', 'center', 'right')),
+    }
+
+    def run(self):
+        doc = self.state.document
+        env = doc.settings.env
+        docdir = os.path.dirname(env.doc2path(env.docname, base=None))
+        filename = self.arguments[0]
+        if filename.startswith('/'):
+            filename = os.path.normpath(filename[1:])
+        else:
+            filename = os.path.normpath(os.path.join(docdir, filename))
+        env.note_dependency(filename)
+        filename = os.path.join(env.srcdir, filename)
+        try:
+            name, data, width, height = render_texfigure(env, filename)
+        except TeXFigureError, exc:
+            return [doc.reporter.error(str(exc))]
+        node = texfigure()
+        node['name'] = name
+        node['data'] = data
+        node['width'] = width
+        node['height'] = height
+        node['alt'] = self.options.get('alt')
+        node['align'] = self.options.get('align')
+        return [node]
+
+
+class TeXFigureError(Exception):
+    pass
+
+
+class texfigure(nodes.General, nodes.Element):
+    pass
+
+
+def render_texfigure(env, filename):
+    directory = os.path.dirname(filename)
+    basename = os.path.basename(filename)
+    stem = os.path.splitext(basename)[0]
+    name = stem + '.png'
+    temp = tempfile.mkdtemp()
+    try:
+        texinputs = [directory]
+        for texdir in env.config.texfigure_texinputs:
+            texdir = os.path.join(env.srcdir, texdir)
+            texinputs.append(texdir)
+        texinputs.append('')
+        texinputs = ':'.join(texinputs)
+        environ = os.environ.copy()
+        environ['TEXINPUTS'] = texinputs
+        cmdline = [env.config.texfigure_pdftex,
+                   '-halt-on-error',
+                   '-interaction', 'nonstopmode',
+                   '-output-directory', temp,
+                   basename]
+        shell(cmdline, env=environ)
+        cmdline = [env.config.texfigure_pdftoppm,
+                   '-r', str(env.config.texfigure_resolution),
+                   '-f', '1', '-l', '1',
+                   os.path.join(temp, stem)+'.pdf',
+                   os.path.join(temp, stem)]
+        shell(cmdline)
+        ppmfile = os.path.join(temp, stem)+'-1.ppm'
+        if not os.path.exists(ppmfile):
+            raise TeXFigureError("file not found: %s" % ppmfile)
+        data = open(ppmfile).read()
+        cmdline = [env.config.texfigure_pnmcrop]
+        data = shell(cmdline, data)
+        line = data.splitlines()[1]
+        width, height = [int(chunk) for chunk in line.split()]
+        cmdline = [env.config.texfigure_pnmtopng,
+                   '-transparent', 'white',
+                   '-compression', '9']
+        data = shell(cmdline, data)
+    finally:
+        shutil.rmtree(temp)
+    return name, data, width, height
+
+
+def shell(cmdline, input=None, env=None):
+    try:
+        process = Popen(cmdline, stdin=PIPE, stdout=PIPE, stderr=PIPE, env=env)
+    except OSError, exc:
+        raise TeXFigureError("cannot start executable `%s`: %s"
+                             % (' '.join(cmdline), exc))
+    output, error = process.communicate(input)
+    if process.returncode != 0:
+        if not error:
+            error = output
+        raise TeXFigureError("`%s` exited with an error:\n%s"
+                             % (' '.join(cmdline), error))
+    return output
+
+
+def visit_texfigure(self, node):
+    href = "%s/%s" % (self.builder.imgpath, node['name'])
+    filename = os.path.join(self.builder.outdir, '_images', node['name'])
+    ensuredir(os.path.dirname(filename))
+    open(filename, 'wb').write(node['data'])
+    if (isinstance(node.parent, nodes.TextElement) or
+        (isinstance(node.parent, nodes.reference) and
+         not isinstance(node.parent.parent, nodes.TextElement))):
+        suffix = ''
+    else:
+        suffix = '\n'
+    atts = {}
+    atts['src'] = href
+    atts['width'] = node['width']
+    atts['height'] = node['height']
+    if node['alt']:
+        atts['alt'] = node['alt']
+    atts['class'] = 'texfigure'
+    if node['align']:
+        atts['class'] += ' align-%s' % node['align']
+    self.body.append(self.emptytag(node, 'img', suffix, **atts))
+
+
+def depart_texfigure(self, node):
+    pass
+
+
+def setup(app):
+    app.add_config_value('texfigure_pdftex', 'pdflatex', 'env')
+    app.add_config_value('texfigure_pdftoppm', 'pdftoppm', 'env')
+    app.add_config_value('texfigure_pnmcrop', 'pnmcrop', 'env')
+    app.add_config_value('texfigure_pnmtopng', 'pnmtopng', 'env')
+    app.add_config_value('texfigure_texinputs', [], 'env')
+    app.add_config_value('texfigure_resolution', 110, 'env')
+    app.add_directive('texfigure', TeXFigureDirective)
+    app.add_node(texfigure,
+                 html=(visit_texfigure, depart_texfigure))
+
+

sphinxcontrib/teximage.py

-#
-# Copyright (c) 2013, Prometheus Research, LLC
-#
-
-
-from docutils import nodes
-from docutils.parsers.rst import Directive, directives
-from sphinx.util.osutil import ensuredir
-from subprocess import Popen, PIPE
-import os, os.path, tempfile, shutil
-
-
-class TeXImageDirective(Directive):
-
-    required_arguments = 1
-    has_content = False
-    option_spec = {
-        'alt': directives.unchanged,
-        'align': lambda arg: directives.choice(arg, ('left', 'center', 'right')),
-    }
-
-    def run(self):
-        doc = self.state.document
-        env = doc.settings.env
-        docdir = os.path.dirname(env.doc2path(env.docname, base=None))
-        filename = self.arguments[0]
-        if filename.startswith('/'):
-            filename = os.path.normpath(filename[1:])
-        else:
-            filename = os.path.normpath(os.path.join(docdir, filename))
-        env.note_dependency(filename)
-        filename = os.path.join(env.srcdir, filename)
-        try:
-            name, data, width, height = render_teximage(env, filename)
-        except TeXImageError, exc:
-            return [doc.reporter.error(str(exc))]
-        node = teximage()
-        node['name'] = name
-        node['data'] = data
-        node['width'] = width
-        node['height'] = height
-        node['alt'] = self.options.get('alt')
-        node['align'] = self.options.get('align')
-        return [node]
-
-
-class TeXImageError(Exception):
-    pass
-
-
-class teximage(nodes.General, nodes.Element):
-    pass
-
-
-def render_teximage(env, filename):
-    directory = os.path.dirname(filename)
-    basename = os.path.basename(filename)
-    stem = os.path.splitext(basename)[0]
-    name = stem + '.png'
-    temp = tempfile.mkdtemp()
-    try:
-        texinputs = [directory]
-        for texdir in env.config.teximage_texinputs:
-            texdir = os.path.join(env.srcdir, texdir)
-            texinputs.append(texdir)
-        texinputs.append('')
-        texinputs = ':'.join(texinputs)
-        environ = os.environ.copy()
-        environ['TEXINPUTS'] = texinputs
-        cmdline = [env.config.teximage_pdftex,
-                   '-halt-on-error',
-                   '-interaction', 'nonstopmode',
-                   '-output-directory', temp,
-                   basename]
-        execute(cmdline, env=environ)
-        cmdline = [env.config.teximage_pdftoppm,
-                   '-r', str(env.config.teximage_resolution),
-                   '-f', '1', '-l', '1',
-                   os.path.join(temp, stem)+'.pdf',
-                   os.path.join(temp, stem)]
-        execute(cmdline)
-        ppmfile = os.path.join(temp, stem)+'-1.ppm'
-        if not os.path.exists(ppmfile):
-            raise TeXImageError("file not found: %s" % ppmfile)
-        data = open(ppmfile).read()
-        cmdline = [env.config.teximage_pnmcrop]
-        data = execute(cmdline, data)
-        line = data.splitlines()[1]
-        width, height = [int(chunk) for chunk in line.split()]
-        cmdline = [env.config.teximage_pnmtopng,
-                   '-transparent', 'white',
-                   '-compression', '9']
-        data = execute(cmdline, data)
-    finally:
-        shutil.rmtree(temp)
-    return name, data, width, height
-
-
-def execute(cmdline, input=None, env=None):
-    try:
-        process = Popen(cmdline, stdin=PIPE, stdout=PIPE, stderr=PIPE, env=env)
-    except OSError, exc:
-        raise TeXImageError("cannot start executable `%s`: %s"
-                            % (' '.join(cmdline), exc))
-    output, error = process.communicate(input)
-    if process.returncode != 0:
-        if not error:
-            error = output
-        raise TeXImageError("`%s` exited with an error:\n%s"
-                            % (' '.join(cmdline), error))
-    return output
-
-
-def visit_teximage(self, node):
-    href = "%s/%s" % (self.builder.imgpath, node['name'])
-    filename = os.path.join(self.builder.outdir, '_images', node['name'])
-    ensuredir(os.path.dirname(filename))
-    open(filename, 'wb').write(node['data'])
-    if (isinstance(node.parent, nodes.TextElement) or
-        (isinstance(node.parent, nodes.reference) and
-         not isinstance(node.parent.parent, nodes.TextElement))):
-        suffix = ''
-    else:
-        suffix = '\n'
-    atts = {}
-    atts['src'] = href
-    atts['width'] = node['width']
-    atts['height'] = node['height']
-    if node['alt']:
-        atts['alt'] = node['alt']
-    atts['class'] = 'teximage'
-    if node['align']:
-        atts['class'] += ' align-%s' % node['align']
-    self.body.append(self.emptytag(node, 'img', suffix, **atts))
-
-
-def depart_teximage(self, node):
-    pass
-
-
-def setup(app):
-    app.add_config_value('teximage_pdftex', 'pdflatex', 'env')
-    app.add_config_value('teximage_pdftoppm', 'pdftoppm', 'env')
-    app.add_config_value('teximage_pnmcrop', 'pnmcrop', 'env')
-    app.add_config_value('teximage_pnmtopng', 'pnmtopng', 'env')
-    app.add_config_value('teximage_texinputs', [], 'env')
-    app.add_config_value('teximage_resolution', 110, 'env')
-    app.add_directive('teximage', TeXImageDirective)
-    app.add_node(teximage,
-                 html=(visit_teximage, depart_teximage))
-
-
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.