Commits

dirkbaechle committed b367651

- wrapped the original actions in pseuo-Builders and added the OpenOffice output format
- added a first simple manual

  • Participants
  • Parent commits 90c5863

Comments (0)

Files changed (5)

+"""SCons.Tool.rest
+
+Tool-specific initialization for the ReST builders.
+
+There normally shouldn't be any need to import this module directly.
+It will usually be imported through the generic SCons.Tool.Tool()
+selection method.
+
+"""
+
+#
+# Copyright (c) 2001-7,2010,2011,2012 The SCons Foundation
+#
+# Permission is hereby granted, free of charge, to any person obtaining
+# a copy of this software and associated documentation files (the
+# "Software"), to deal in the Software without restriction, including
+# without limitation the rights to use, copy, modify, merge, publish,
+# distribute, sublicense, and/or sell copies of the Software, and to
+# permit persons to whom the Software is furnished to do so, subject to
+# the following conditions:
+#
+# The above copyright notice and this permission notice shall be included
+# in all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
+# KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
+# WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+# NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+# LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+# OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+# WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+#
+
+import os
+
+import SCons.Action
 import SCons.Builder
+import SCons.Util
 
-from docutils.core import publish_file
-from docutils.frontend import Values
+try:
+    import locale
+    locale.setlocale(locale.LC_ALL, '')
+except:
+    pass
+
+has_docutils = True
+try:
+    from docutils.core import publish_file
+    from docutils.core import publish_cmdline_to_binary
+    from docutils.frontend import Values
+    from docutils.writers.odf_odt import Writer
+    from docutils.writers.odf_odt import Reader
+except:
+    has_docutils = False
+
 
 def rst2something(target, source, env, validOptions, writer):
+    if not has_docutils:
+        return
+
     # Find variables that can be passed to docutils.
     settings = dict([item for item in env.items() if item[0] in validOptions])
 
                      writer_name=writer,
                      settings_overrides=settings)
 
+#
+# Warnings
+#
+class ToolReSTWarning(SCons.Warnings.Warning):
+    pass
 
+class ReSTNotFound(ToolReSTWarning):
+    pass
+
+SCons.Warnings.enableWarningClass(ToolReSTWarning)
+
+#
+# Detect tool
+#
+def _detect(env):
+    """ Try to detect the ReST command line tools, here rst2html """
+    rest = env.WhereIs('rst2html')
+    if rest:
+        return rest
+
+    raise SCons.Errors.StopError(
+        ReSTNotFound,
+        "Could not detect ReST builder")
+    return None
+
+#
+# Actions
+#
 def rst2latex(target, source, env):
     options = ['stylesheet', 'embed_stylesheet']
     rst2something(target, source, env, options, 'latex')
     return None
 
-rst2latexBldr = SCons.Builder.Builder(
-    action = rst2latex,
-    suffix = '.tex',
-    src_suffix = '.rst'
-)
-
 def rst2html(target, source, env):
     options = ['stylesheet', 'embed_stylesheet']
     rst2something(target, source, env, options, 'html4css1')
     return None
 
-rst2htmlBldr = SCons.Builder.Builder(
-    action = rst2html,
-    suffix = '.html',
-    src_suffix = '.rst'
-)
+def rst2odt(target, source, env):
+    if not has_docutils:
+        return None
+
+    writer = Writer()
+    reader = Reader()
+    for i in range(len(source)):
+        publish_cmdline_to_binary(reader=reader, writer=writer, argv=[str(source[i]), str(target[i])])
+    return None
+
+#
+# Builders
+#
+__rest_latexbuilder = SCons.Builder.Builder(
+        action = rst2latex,
+        suffix = '$REST_LATEXSUFFIX',
+        src_suffix = '$REST_SUFFIX')
+
+__rest_htmlbuilder = SCons.Builder.Builder(
+        action = rst2html,
+        suffix = '$REST_HTMLSUFFIX',
+        src_suffix = '$REST_SUFFIX')
+
+__rest_odtbuilder = SCons.Builder.Builder(
+        action = rst2odt,
+        suffix = '$REST_ODTSUFFIX',
+        src_suffix = '$REST_SUFFIX')
+
+def Rst2Latex(env, target, source=None, *args, **kw):
+    """
+    A pseudo-Builder wrapper for ReST->LaTeX.
+    """
+    if not SCons.Util.is_List(target):
+        target = [target]
+    if not source:
+        source = target[:]
+        target = []
+        for s in source:
+            sourceBase, sourceExt = os.path.splitext(SCons.Util.to_String(s))
+            target.append(sourceBase)
+
+    if not SCons.Util.is_List(source):
+        source = [source]
+
+    result = []
+    for t, s in zip(target, source):
+        # Call builder
+        result.extend(__rest_latexbuilder.__call__(env, t, s, **kw))
+
+    return result
+
+def Rst2Html(env, target, source=None, *args, **kw):
+    """
+    A pseudo-Builder wrapper for ReST->HTML.
+    """
+    if not SCons.Util.is_List(target):
+        target = [target]
+    if not source:
+        source = target[:]
+        target = []
+        for s in source:
+            sourceBase, sourceExt = os.path.splitext(SCons.Util.to_String(s))
+            target.append(sourceBase)
+
+    if not SCons.Util.is_List(source):
+        source = [source]
+
+    result = []
+    for t, s in zip(target, source):
+        # Call builder
+        result.extend(__rest_htmlbuilder.__call__(env, t, s, **kw))
+
+    return result
+
+def Rst2Odt(env, target, source=None, *args, **kw):
+    """
+    A pseudo-Builder wrapper for ReST->Odt.
+    """
+    if not SCons.Util.is_List(target):
+        target = [target]
+    if not source:
+        source = target[:]
+        target = []
+        for s in source:
+            sourceBase, sourceExt = os.path.splitext(SCons.Util.to_String(s))
+            target.append(sourceBase)
+
+    if not SCons.Util.is_List(source):
+        source = [source]
+
+    result = []
+    for t, s in zip(target, source):
+        # Call builder
+        result.extend(__rest_odtbuilder.__call__(env, t, s, **kw))
+
+    return result
 
 def generate(env):
-    env['BUILDERS']['Rst2Latex'] = rst2latexBldr
-    env['BUILDERS']['Rst2Html'] = rst2htmlBldr
+    """Add Builders and construction variables to the Environment."""
 
+    env.SetDefault(
+        # Suffixes/prefixes
+        REST_SUFFIX = '.rst',
+        REST_LATEXSUFFIX = '.ltx',
+        REST_HTMLSUFFIX = '.html',
+        REST_ODTSUFFIX = '.odt',
+        )
+
+    try:
+        env.AddMethod(Rst2Latex, "Rst2Latex")
+        env.AddMethod(Rst2Html, "Rst2Html")
+        env.AddMethod(Rst2Odt, "Rst2Odt")
+    except AttributeError:
+        # Looks like we use a pre-0.98 version of SCons...
+        from SCons.Script.SConscript import SConsEnvironment
+        SConsEnvironment.Rst2Latex = Rst2Latex
+        SConsEnvironment.Rst2Html = Rst2Html
+        SConsEnvironment.Rst2Odt = Rst2Odt
 
 def exists(env):
-    return env.Detect('rst2latex') or env.Detect('rst2html')
+    return _detect(env)
 
+#
+# Copyright (c) 2001-2010 The SCons Foundation
+#
+# Permission is hereby granted, free of charge, to any person obtaining
+# a copy of this software and associated documentation files (the
+# "Software"), to deal in the Software without restriction, including
+# without limitation the rights to use, copy, modify, merge, publish,
+# distribute, sublicense, and/or sell copies of the Software, and to
+# permit persons to whom the Software is furnished to do so, subject to
+# the following conditions:
+#
+# The above copyright notice and this permission notice shall be included
+# in all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
+# KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
+# WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+# NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+# LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+# OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+# WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+
+import os
+
+env = Environment(ENV = os.environ,
+                  tools = ['docbook'])
+
+env.DocbookPdf('manual', xsl='pdf.xsl')
+
+env.DocbookHtml('manual', xsl='html.xsl')
+
+<?xml version='1.0'?>
+<!--
+
+  Copyright (c) 2001-2010 The SCons Foundation
+
+  Permission is hereby granted, free of charge, to any person obtaining
+  a copy of this software and associated documentation files (the
+  "Software"), to deal in the Software without restriction, including
+  without limitation the rights to use, copy, modify, merge, publish,
+  distribute, sublicense, and/or sell copies of the Software, and to
+  permit persons to whom the Software is furnished to do so, subject to
+  the following conditions:
+
+  The above copyright notice and this permission notice shall be included
+  in all copies or substantial portions of the Software.
+
+  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
+  KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
+  WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+  NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+  LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+  OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+  WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+-->
+<xsl:stylesheet
+	xmlns:xsl="http://www.w3.org/1999/XSL/Transform" 
+	xmlns:fo="http://www.w3.org/1999/XSL/Format" 
+	version="1.0"> 
+
+	<xsl:import href="file:///usr/share/xml/docbook/stylesheet/docbook-xsl/html/docbook.xsl"/> 
+
+<xsl:param name="l10n.gentext.default.language" select="'en'"/>
+<xsl:param name="section.autolabel" select="1"/>
+<xsl:param name="html.stylesheet" select="'scons.css'"/>
+<xsl:param name="generate.toc">
+/appendix toc,title
+article/appendix  nop
+/article  toc,title
+book      toc,title,figure,table,example,equation
+/chapter  toc,title
+part      toc,title
+/preface  toc,title
+reference toc,title
+/sect1    toc
+/sect2    toc
+/sect3    toc
+/sect4    toc
+/sect5    toc
+/section  toc
+set       toc,title
+</xsl:param>
+
+</xsl:stylesheet> 
+
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+
+  Copyright (c) 2001-2010 The SCons Foundation
+
+  Permission is hereby granted, free of charge, to any person obtaining
+  a copy of this software and associated documentation files (the
+  "Software"), to deal in the Software without restriction, including
+  without limitation the rights to use, copy, modify, merge, publish,
+  distribute, sublicense, and/or sell copies of the Software, and to
+  permit persons to whom the Software is furnished to do so, subject to
+  the following conditions:
+
+  The above copyright notice and this permission notice shall be included
+  in all copies or substantial portions of the Software.
+
+  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
+  KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
+  WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+  NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+  LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+  OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+  WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+-->
+<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
+<article>
+  <title>The SCons reST tool</title>
+  <articleinfo>
+    <author>
+      <surname>Dirk Baechle</surname>
+    </author>
+    <pubdate>2012-04-25</pubdate>
+  </articleinfo>
+<section id="basics"><title>Basics</title>
+<para>This tool tries to make working with docutils in SCons a little easier.
+It provides several toolchains for creating different output formats,
+like HTML or LaTeX, from a reST (reStructuredText) input file.
+</para>
+<section id="install"><title>Install</title>
+<para>Installing it, requires you to copy (or, even better: checkout) the contents of the
+package's <literal>rest</literal> folder to
+</para>
+<orderedlist><listitem><para><quote><literal>/path_to_your_project/site_scons/site_tools/rest</literal></quote>, if you need the reST Tool in one project only, or
+</para>
+</listitem>
+<listitem><para><quote><literal>~/.scons/site_scons/site_tools/rest</literal></quote>, for a system-wide installation under your current login.
+</para>
+</listitem>
+</orderedlist>
+<para>For more infos about this, please refer to 
+</para>
+<itemizedlist><listitem><para>the SCons User's Guide, chap. 19.7 "Where to put your custom Builders and Tools" and
+</para>
+</listitem>
+<listitem><para>the SCons Tools Wiki page at <ulink url="http://scons.org/wiki/ToolsIndex">http://scons.org/wiki/ToolsIndex</ulink>.
+</para>
+</listitem>
+</itemizedlist>
+</section>
+<section id="activation"><title>How to activate</title>
+<para>For activating the tool "rest", you have to add its name to the Environment constructor,
+like this
+</para>
+<screen>env = Environment(tools=['rest'])
+</screen>
+<para>On its startup, the reST tool tries to find an installed version of the <literal>docutils</literal> package by
+looking for the command-line tool <literal>rst2html</literal>. So make sure that it is added to your system's environment
+<literal>PATH</literal> and can be called directly, without specifying its full path.
+</para>
+</section>
+<section id="requirements"><title>Requirements</title>
+<para>For the most basic processing of reST to HTML/LaTeX/ODT, you need to have installed
+</para>
+<itemizedlist><listitem><para>the Python <literal>docutils</literal> package, and optionally
+</para>
+</listitem>
+<listitem><para>the <literal>pygment</literal> module for syntax highlighting in code blocks.
+</para>
+</listitem>
+</itemizedlist>
+</section>
+</section>
+<section id="process"><title>Processing documents</title>
+<para>Creating a HTML or LaTeX document is very simple and straightforward. Say
+</para>
+<screen>env = Environment(tools=['rest'])
+env.Rst2Html('manual.html', 'manual.rst')
+env.Rst2Latex('manual.ltx', 'manual.rst')
+</screen>
+<para>to get both outputs from your source file <literal>manual.rst</literal>. As a shortcut, you can
+give the stem of the filenames alone, like this:
+</para>
+<screen>env = Environment(tools=['rest'])
+env.Rst2Html('manual')
+env.Rst2Latex('manual')
+</screen>
+<para>and get the same result. Target and source lists are also supported:
+</para>
+<screen>env = Environment(tools=['rest'])
+env.Rst2Html(['manual.html','reference.html'], ['manual.rst','reference.rst'])
+</screen>
+<para>or even
+</para>
+<screen>env = Environment(tools=['rest'])
+env.Rst2Html(['manual','reference'])
+</screen>
+<important><para>Whenever you leave out the list of sources, you may not specify a file extension! The
+Tool uses the given names as file stems, and adds the suffixes for target and source files
+accordingly.
+</para>
+</important>
+<para>The rules given above are valid for all the Builders <literal>Rst2Html</literal>, <literal>Rst2Latex</literal> 
+and <literal>Rst2Odt</literal>. 
+</para>
+</section>
+<section id="builders"><title>All builders</title>
+<para>A simple list of all builders currently available:
+</para>
+<variablelist><varlistentry><term>Rst2Html
+</term>
+<listitem><para>Single HTML file.
+</para>
+</listitem>
+</varlistentry>
+<varlistentry><term>Rst2Latex
+</term>
+<listitem><para>Outputs a LaTeX file.
+</para>
+</listitem>
+</varlistentry>
+<varlistentry><term>Rst2Odt
+</term>
+<listitem><para>OpenOffice output.
+</para>
+</listitem>
+</varlistentry>
+</variablelist>
+</section>
+<section id="more"><title>Need more?</title>
+<para>This work is still in a very basic state and hasn't been tested well
+with things like variant dirs, yet. 
+There will definitely arise the need for
+adding features, or a variable. Let us know if you can think of a nice
+improvement or have worked on a bugfix/patch with success. Enter your issues at the
+Bitbucket bug tracker for the ReST Tool, or write to the User General Discussion
+list of SCons at <literal>users@scons.tigris.org</literal>.
+</para>
+</section>
+
+</article>
+<?xml version='1.0'?>
+<!--
+
+  Copyright (c) 2001-2010 The SCons Foundation
+
+  Permission is hereby granted, free of charge, to any person obtaining
+  a copy of this software and associated documentation files (the
+  "Software"), to deal in the Software without restriction, including
+  without limitation the rights to use, copy, modify, merge, publish,
+  distribute, sublicense, and/or sell copies of the Software, and to
+  permit persons to whom the Software is furnished to do so, subject to
+  the following conditions:
+
+  The above copyright notice and this permission notice shall be included
+  in all copies or substantial portions of the Software.
+
+  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
+  KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
+  WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+  NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+  LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+  OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+  WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+-->
+
+<xsl:stylesheet
+	xmlns:xsl="http://www.w3.org/1999/XSL/Transform" 
+	xmlns:fo="http://www.w3.org/1999/XSL/Format" 
+	version="1.0"> 
+
+	<xsl:import href="file:///usr/share/xml/docbook/stylesheet/docbook-xsl/fo/docbook.xsl"/> 
+
+<xsl:param name="l10n.gentext.default.language" select="'en'"/>
+<xsl:param name="section.autolabel" select="1"></xsl:param>
+<xsl:param name="toc.indent.width" select="0"></xsl:param>
+<xsl:param name="body.start.indent">0pt</xsl:param>
+<xsl:param name="shade.verbatim" select="1"></xsl:param>
+<xsl:param name="generate.toc">
+/appendix toc,title
+article/appendix  nop
+/article  toc,title
+book      toc,title,figure,table,example,equation
+/chapter  toc,title
+part      toc,title
+/preface  toc,title
+reference toc,title
+/sect1    toc
+/sect2    toc
+/sect3    toc
+/sect4    toc
+/sect5    toc
+/section  toc
+set       toc,title
+</xsl:param>
+
+<xsl:template match="varlistentry/term">
+	<xsl:call-template name="inline.boldseq"/>
+</xsl:template>
+
+</xsl:stylesheet> 
+