diff options
| author | milde <milde@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> | 2007-06-28 08:09:06 +0000 |
|---|---|---|
| committer | milde <milde@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> | 2007-06-28 08:09:06 +0000 |
| commit | aa9e09501709665eec25973aecbeb5c4b00d2ce0 (patch) | |
| tree | 2fd6586703b8286c07fbbc126b2050d8119402bb /sandbox/code-block-directive | |
| parent | f27b0d0364d3956c11b178938c57b5ca87c18884 (diff) | |
| download | docutils-aa9e09501709665eec25973aecbeb5c4b00d2ce0.tar.gz | |
Moved the stylesheets to data/ sub-directory.
git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk@5300 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
Diffstat (limited to 'sandbox/code-block-directive')
12 files changed, 229 insertions, 70 deletions
diff --git a/sandbox/code-block-directive/README.txt b/sandbox/code-block-directive/README.txt index 61ed3614b..c057a9716 100644 --- a/sandbox/code-block-directive/README.txt +++ b/sandbox/code-block-directive/README.txt @@ -25,13 +25,15 @@ See `syntax-highlight.html`_ for the full picture. front end for reStructuredText -> HTML conversion supporting the "code-block" directive. +data_ + Style sheets + docs_ Documentation, concepts, discussion, examples... - tools_ - Style sheets, alternative (legacy) front ends, script for interactive - testing. + Alternative (legacy) front ends, + script for interactive testing. .. References @@ -42,6 +44,7 @@ tools_ .. _pygments_code_block_directive-bunt.py.html: docs/pygments_code_block_directive-bunt.py.html .. _rst2html-highlight: rst2html-highlight +.. _data: data .. _docs: docs .. _tools: tools .. _syntax-highlight.html: docs/syntax-highlight.html diff --git a/sandbox/code-block-directive/tools/pygments-default.css b/sandbox/code-block-directive/data/pygments-default.css index 5d933198c..5d933198c 100644 --- a/sandbox/code-block-directive/tools/pygments-default.css +++ b/sandbox/code-block-directive/data/pygments-default.css diff --git a/sandbox/code-block-directive/tools/pygments-default.sty b/sandbox/code-block-directive/data/pygments-default.sty index d1567557a..d1567557a 100644 --- a/sandbox/code-block-directive/tools/pygments-default.sty +++ b/sandbox/code-block-directive/data/pygments-default.sty diff --git a/sandbox/code-block-directive/tools/pygments-long.css b/sandbox/code-block-directive/data/pygments-long.css index f05d26d30..f05d26d30 100644 --- a/sandbox/code-block-directive/tools/pygments-long.css +++ b/sandbox/code-block-directive/data/pygments-long.css diff --git a/sandbox/code-block-directive/data/rst2html-pygments b/sandbox/code-block-directive/data/rst2html-pygments new file mode 100755 index 000000000..c227bbf2e --- /dev/null +++ b/sandbox/code-block-directive/data/rst2html-pygments @@ -0,0 +1,60 @@ +#!/usr/bin/python + +# :Author: David Goodger, a Pygments author|contributor, Guenter Milde +# :Date: $Date: $ +# :Copyright: This module has been placed in the public domain. + +# This is a merge of the docutils_ `rst2html` front end with an extension +# suggestion taken from the pygments_ documentation. + +""" +A front end to docutils, producing HTML with syntax colouring using pygments +""" + +try: + import locale + locale.setlocale(locale.LC_ALL, '') +except: + pass + +from docutils.core import publish_cmdline, default_description + +description = ('Generates (X)HTML documents from standalone reStructuredText ' + 'sources. Uses `pygments` to colorize the content of' + '"code-block" directives. Needs an adapted stylesheet' + + default_description) + +# Define a new directive `code-block` that uses the `pygments` source +# highlighter to render code in color. +# +# Code from the `pygments`_ documentation for `Using Pygments in ReST +# documents`_. + +from docutils import nodes +from docutils.parsers.rst import directives +from pygments import highlight +from pygments.lexers import get_lexer_by_name +from pygments.formatters import HtmlFormatter + +pygments_formatter = HtmlFormatter() + +def pygments_directive(name, arguments, options, content, lineno, + content_offset, block_text, state, state_machine): + try: + lexer = get_lexer_by_name(arguments[0]) + except ValueError: + # no lexer found - use the text one instead of an exception + lexer = get_lexer_by_name('text') + parsed = highlight(u'\n'.join(content), lexer, pygments_formatter) + return [nodes.raw('', parsed, format='html')] +pygments_directive.arguments = (1, 0, 1) +pygments_directive.content = 1 +directives.register_directive('code-block', pygments_directive) + +# Call the docutils publisher to render the input as html:: + +publish_cmdline(writer_name='html', description=description) + +# .. _doctutile: http://docutils.sf.net/ +# .. _pygments: http://pygments.org/ +# .. _Using Pygments in ReST documents: http://pygments.org/docs/rstdirective/ diff --git a/sandbox/code-block-directive/docs/for-else-test.py b/sandbox/code-block-directive/docs/for-else-test.py new file mode 100644 index 000000000..d3edf4400 --- /dev/null +++ b/sandbox/code-block-directive/docs/for-else-test.py @@ -0,0 +1,85 @@ +# Example for syntax highlight with Pygments +# ========================================== +# +# Translate this document to HTML with a pygments enhanced frontend:: +# +# rst2html-pygments --stylesheet=pygments-default.css +# +# or to LaTeX with:: +# +# rst2latex-pygments --stylesheet=pygments-default.sty +# +# to gain syntax highlight in the output. +# +# .. Run the doctests with ``pylit --doctest for-else-test.py``. +# +# +# for-else-test +# ------------- +# +# Test the flow in a `for` loop with `else` statement. +# +# First define a simple `for` loop. +# +# .. code-block:: python + +def loop1(iterable): + """simple for loop with `else` statement""" + for i in iterable: + print i + else: + print "iterable empty" + print "Ende" + +# Now test it: +# +# The first test runs as I expect: iterator empty -> else clause applies: +# +# .. code-block:: pycon +# +# >>> loop1(range(0)) +# iterable empty +# Ende +# +# However, the else clause even runs if the iterator is not empty in the first +# place but after it is "spent": +# +# .. code-block:: pycon +# +# >>> loop1(range(3)) +# 0 +# 1 +# 2 +# iterable empty +# Ende +# +# It seems like the else clause can only be prevented, if we break out of +# the loop. Let's try +# +# .. code-block:: python + +def loop2(iterable): + """for loop with `break` and `else` statement""" + for i in iterable: + print i + break + else: + print "iterable empty" + print "Ende" + +# And indeed, the else clause is skipped after breaking out of the loop: +# +# .. code-block:: pycon +# +# >>> loop2(range(3)) +# 0 +# Ende +# +# The empty iterator runs as expected: +# +# .. code-block:: pycon +# +# >>> loop2(range(0)) +# iterable empty +# Ende +# diff --git a/sandbox/code-block-directive/docs/for-else-test.py.html b/sandbox/code-block-directive/docs/for-else-test.py.html index bc3ca5fb9..1e6057be1 100644 --- a/sandbox/code-block-directive/docs/for-else-test.py.html +++ b/sandbox/code-block-directive/docs/for-else-test.py.html @@ -17,9 +17,8 @@ /* This stylesheet provides syntax highlight for documents generated with a */ /* pygments_ enhanced reStructured Text -> html converter. */ -/* import the default docutils style sheet */ +/* Import the default docutils style sheet */ /* --------------------------------------- */ - /* :: */ @import url("/stylesheets/html4css1.css"); @@ -28,7 +27,7 @@ /* --------------------- */ /* Content copied from the `html4css1.css` rule for literal blocks. */ -/* Selector adapted to the output of Pygments_. */ +/* Selector adapted to the output of Pygments_. :: */ div.highlight { margin-left: 2em ; @@ -102,14 +101,13 @@ div.highlight { .vi { color: #B8860B } /* Name.Variable.Instance */ .il { color: #666666 } /* Literal.Number.Integer.Long */ -/* .. _pygments: http://pygments.org/ */ +/* .. _pygments: http://pygments.org/ */ </style> </head> <body> <div class="document" id="example-for-syntax-highlight-with-pygments"> <h1 class="title">Example for syntax highlight with Pygments</h1> -<!-- # -*- rst-mode -*- --> <p>Translate this document to HTML with a pygments enhanced frontend:</p> <pre class="literal-block"> rst2html-pygments --stylesheet=pygments-default.css @@ -119,7 +117,14 @@ rst2html-pygments --stylesheet=pygments-default.css rst2latex-pygments --stylesheet=pygments-default.sty </pre> <p>to gain syntax highlight in the output.</p> -<!-- Run the doctests with ``pylit - -doctest for-else-test.py``. --> +<p>Convert between text <-> code source formats with:</p> +<pre class="literal-block"> +pylit --code-block-marker='.. code-block:: python' +</pre> +<p>Run the doctests with:</p> +<pre class="literal-block"> +pylit --doctest for-else-test.py +</pre> <div class="section"> <h1><a id="for-else-test" name="for-else-test">for-else-test</a></h1> <p>Test the flow in a <cite>for</cite> loop with <cite>else</cite> statement.</p> @@ -134,7 +139,8 @@ rst2latex-pygments --stylesheet=pygments-default.sty </pre></div> <p>Now test it:</p> <p>The first test runs as I expect: iterator empty -> else clause applies:</p> -<div class="highlight"><pre><span class="gp">>>> </span><span class="n">loop1</span><span class="p">(</span><span class="nb">range</span><span class="p">(</span><span class="mi">0</span><span class="p">))</span> +<div class="highlight"><pre><span class="gp">>>> </span><span class="nb">execfile</span><span class="p">(</span><span class="s">'for-else-test.py'</span><span class="p">)</span> +<span class="gp">>>> </span><span class="n">loop1</span><span class="p">(</span><span class="nb">range</span><span class="p">(</span><span class="mi">0</span><span class="p">))</span> <span class="go">iterable empty</span> <span class="go">Ende</span> </pre></div> @@ -172,7 +178,7 @@ the loop. Let's try</p> </div> <div class="footer"> <hr class="footer" /> -Generated on: 2007-05-29. +Generated on: 2007-06-21. </div> </body> diff --git a/sandbox/code-block-directive/docs/for-else-test.py.txt b/sandbox/code-block-directive/docs/for-else-test.py.txt index b5ba05848..d9687ecd5 100644 --- a/sandbox/code-block-directive/docs/for-else-test.py.txt +++ b/sandbox/code-block-directive/docs/for-else-test.py.txt @@ -1,5 +1,3 @@ -.. # -*- rst-mode -*- - Example for syntax highlight with Pygments ========================================== @@ -13,7 +11,13 @@ or to LaTeX with:: to gain syntax highlight in the output. -.. Run the doctests with ``pylit --doctest for-else-test.py``. +Convert between text <-> code source formats with:: + + pylit --code-block-marker='.. code-block:: python' + +Run the doctests with:: + + pylit --doctest for-else-test.py for-else-test @@ -25,63 +29,64 @@ First define a simple `for` loop. .. code-block:: python - def loop1(iterable): - """simple for loop with `else` statement""" - for i in iterable: - print i - else: - print "iterable empty" - print "Ende" - + def loop1(iterable): + """simple for loop with `else` statement""" + for i in iterable: + print i + else: + print "iterable empty" + print "Ende" + Now test it: The first test runs as I expect: iterator empty -> else clause applies: .. code-block:: pycon - >>> loop1(range(0)) - iterable empty - Ende - + >>> execfile('for-else-test.py') + >>> loop1(range(0)) + iterable empty + Ende + However, the else clause even runs if the iterator is not empty in the first place but after it is "spent": .. code-block:: pycon - >>> loop1(range(3)) - 0 - 1 - 2 - iterable empty - Ende - + >>> loop1(range(3)) + 0 + 1 + 2 + iterable empty + Ende + It seems like the else clause can only be prevented, if we break out of the loop. Let's try .. code-block:: python - def loop2(iterable): - """for loop with `break` and `else` statement""" - for i in iterable: - print i - break - else: - print "iterable empty" - print "Ende" - + def loop2(iterable): + """for loop with `break` and `else` statement""" + for i in iterable: + print i + break + else: + print "iterable empty" + print "Ende" + And indeed, the else clause is skipped after breaking out of the loop: .. code-block:: pycon - >>> loop2(range(3)) - 0 - Ende - + >>> loop2(range(3)) + 0 + Ende + The empty iterator runs as expected: .. code-block:: pycon - >>> loop2(range(0)) - iterable empty - Ende - + >>> loop2(range(0)) + iterable empty + Ende + diff --git a/sandbox/code-block-directive/docs/myfunction.py.html b/sandbox/code-block-directive/docs/myfunction.py.html index eb3365b00..edc700246 100644 --- a/sandbox/code-block-directive/docs/myfunction.py.html +++ b/sandbox/code-block-directive/docs/myfunction.py.html @@ -5,7 +5,7 @@ <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" /> <meta name="generator" content="Docutils 0.4.1: http://docutils.sourceforge.net/" /> <title></title> -<link rel="stylesheet" href="../tools/pygments-default.css" type="text/css" /> +<link rel="stylesheet" href="../data/pygments-default.css" type="text/css" /> </head> <body> <div class="document"> diff --git a/sandbox/code-block-directive/docs/pygments_code_block_directive-bunt.py.html b/sandbox/code-block-directive/docs/pygments_code_block_directive-bunt.py.html index c44f69e9b..78bb809e9 100644 --- a/sandbox/code-block-directive/docs/pygments_code_block_directive-bunt.py.html +++ b/sandbox/code-block-directive/docs/pygments_code_block_directive-bunt.py.html @@ -155,7 +155,7 @@ if pygments not found)</td> </table> <!-- to get the syntax highlight in the html output of this file, convert with:: -./rst2html-highlight - -stylesheet=tools/pygments-default.css --> +./rst2html-highlight - -stylesheet=data/pygments-default.css --> <pre class="code-block python literal-block"> <span class="sd">"""Define and register a code-block directive using pygments """</span> diff --git a/sandbox/code-block-directive/docs/syntax-highlight.html b/sandbox/code-block-directive/docs/syntax-highlight.html index 1591b6777..da8b535ff 100644 --- a/sandbox/code-block-directive/docs/syntax-highlight.html +++ b/sandbox/code-block-directive/docs/syntax-highlight.html @@ -5,7 +5,7 @@ <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" /> <meta name="generator" content="Docutils 0.4.1: http://docutils.sourceforge.net/" /> <title>Syntax Highlight</title> -<link rel="stylesheet" href="../../../../../lib/python2.4/site-packages/docutils/writers/html4css1/html4css1.css" type="text/css" /> +<link rel="stylesheet" href="/usr/lib/python2.4/site-packages/docutils/writers/html4css1/html4css1.css" type="text/css" /> </head> <body> <div class="document" id="syntax-highlight"> @@ -20,7 +20,7 @@ </ul> </li> <li><a class="reference" href="#proposal-for-a-code-block-directive-in-docutils" id="id12" name="id12">3 Proposal for a code-block directive in docutils</a><ul class="auto-toc"> -<li><a class="reference" href="#parsing" id="id13" name="id13">3.1 Parsing</a></li> +<li><a class="reference" href="#reading" id="id13" name="id13">3.1 Reading</a></li> <li><a class="reference" href="#writing" id="id14" name="id14">3.2 Writing</a></li> <li><a class="reference" href="#todo" id="id15" name="id15">3.3 TODO</a></li> </ul> @@ -162,9 +162,9 @@ pylit.py.)</p> <col class="field-name" /> <col class="field-body" /> <tbody valign="top"> -<tr class="field"><th class="field-name">CSS stylesheet:</th><td class="field-body"><a class="reference" href="../tools/pygments-default.css">pygments-default.css</a></td> +<tr class="field"><th class="field-name">CSS stylesheet:</th><td class="field-body"><a class="reference" href="../data/pygments-default.css">pygments-default.css</a></td> </tr> -<tr class="field"><th class="field-name">LaTeX style:</th><td class="field-body"><a class="reference" href="../tools/pygments-default.sty">pygments-default.sty</a></td> +<tr class="field"><th class="field-name">LaTeX style:</th><td class="field-body"><a class="reference" href="../data/pygments-default.sty">pygments-default.sty</a></td> </tr> </tbody> </table> @@ -208,13 +208,13 @@ fixed-width font) if <tt class="docutils literal"><span class="pre">import</span </blockquote> <p>Implemented 2007-06-08.</p> <div class="section"> -<h2><a class="toc-backref" href="#id13" id="parsing" name="parsing">3.1 Parsing</a></h2> +<h2><a class="toc-backref" href="#id13" id="reading" name="reading">3.1 Reading</a></h2> <p>Felix Wiemann provided a <a class="reference" href="http://article.gmane.org/gmane.text.docutils.user/3689">proof of concept</a> script that utilizes the <a class="reference" href="http://pygments.org/">pygments</a> parser to parse a source code string and store the result in the document tree.</p> -<p>This concept is used in <a class="reference" href="pygments_code_block_directive.py.html">pygments_code_block_directive</a>, (source: -<a class="reference" href="../pygments_code_block_directive.py">pygments_code_block_directive.py</a>), to define and register a "code-block" -directive.</p> +<p>This concept is used in <a class="reference" href="../pygments_code_block_directive.py">pygments_code_block_directive.py</a>, (HTML rendering +of the literate code: <a class="reference" href="pygments_code_block_directive-bunt.py.html">pygments_code_block_directive</a>), to define +and register a "code-block" directive.</p> <ul class="simple"> <li>The <cite>DocutilsInterface</cite> class uses <a class="reference" href="http://pygments.org/">pygments</a> to parse the content of the directive and classify the tokens using short CSS class names identical to @@ -237,7 +237,7 @@ use it or to pass it on.</p> <ul class="simple"> <li>The <a class="reference" href="../tools/rst2html-highlight">rst2html-highlight</a> front end registers the "code-block" directive and converts an input file to html.</li> -<li>Styling is done with the adapted CSS style sheet <a class="reference" href="../tools/pygments-default.css">pygments-default.css</a> +<li>Styling is done with the adapted CSS style sheet <a class="reference" href="../data/pygments-default.css">pygments-default.css</a> based on docutils' default stylesheet and the output of <tt class="docutils literal"><span class="pre">pygmentize</span> <span class="pre">-S</span> <span class="pre">default</span> <span class="pre">-f</span> <span class="pre">html</span></tt>.</li> <li>The result looks like <a class="reference" href="myfunction.py.html">myfunction.py.html</a>.</li> @@ -410,7 +410,7 @@ docutils</a>. It would need</p> <div class="footer"> <hr class="footer" /> <a class="reference" href="syntax-highlight.txt">View document source</a>. -Generated on: 2007-06-08. +Generated on: 2007-06-28. </div> </body> diff --git a/sandbox/code-block-directive/docs/syntax-highlight.txt b/sandbox/code-block-directive/docs/syntax-highlight.txt index 954f10eab..ef5af4067 100644 --- a/sandbox/code-block-directive/docs/syntax-highlight.txt +++ b/sandbox/code-block-directive/docs/syntax-highlight.txt @@ -178,16 +178,16 @@ On 7.06.07, David Goodger wrote: Implemented 2007-06-08. -Parsing +Reading """"""" Felix Wiemann provided a `proof of concept`_ script that utilizes the pygments_ parser to parse a source code string and store the result in the document tree. -This concept is used in `pygments_code_block_directive`_, (source: -`pygments_code_block_directive.py`_), to define and register a "code-block" -directive. +This concept is used in `pygments_code_block_directive.py`_, (HTML rendering +of the literate code: `pygments_code_block_directive`_), to define +and register a "code-block" directive. * The `DocutilsInterface` class uses pygments_ to parse the content of the directive and classify the tokens using short CSS class names identical to @@ -257,7 +257,7 @@ TODO .. _proof of concept: http://article.gmane.org/gmane.text.docutils.user/3689 .. _pygments_code_block_directive.py: ../pygments_code_block_directive.py -.. _pygments_code_block_directive: pygments_code_block_directive.py.html +.. _pygments_code_block_directive: pygments_code_block_directive-bunt.py.html .. _pygments_docutils_interface.py: pygments_docutils_interface.py .. _myfunction.py.txt: myfunction.py.txt .. _myfunction.py.xml: myfunction.py.xml @@ -267,7 +267,7 @@ TODO .. _myfunction.py.newlatex2e.tex: myfunction.py.newlatex2e.tex .. _myfunction.py.newlatex2e.pdf: myfunction.py.newlatex2e.pdf .. _rst2html-highlight: ../tools/rst2html-highlight -.. _pygments-long.css: ../tools/pygments-long.css +.. _pygments-long.css: ../data/pygments-long.css @@ -437,6 +437,6 @@ docutils`_. It would need .. _for-else-test.py.txt: for-else-test.py.txt .. _for-else-test.py.tex: for-else-test.py.tex .. _for-else-test.py.pdf: for-else-test.py.pdf -.. _pygments-default.css: ../tools/pygments-default.css -.. _pygments-default.sty: ../tools/pygments-default.sty +.. _pygments-default.css: ../data/pygments-default.css +.. _pygments-default.sty: ../data/pygments-default.sty |