Some text and ' @@ -41,7 +43,7 @@ * ``pos`` is a ``(filename, lineno, column)`` tuple that describes where the event “comes from”. -:: +.. code-block:: pycon >>> for kind, data, pos in stream: ... print kind, `data`, pos @@ -64,7 +66,9 @@ stream, either filters that come with Genshi, or your own custom filters. A filter is simply a callable that accepts the stream as parameter, and returns -the filtered stream:: +the filtered stream: + +.. code-block:: python def noop(stream): """A filter that doesn't actually do anything with the stream.""" @@ -72,17 +76,23 @@ yield kind, data, pos Filters can be applied in a number of ways. The simplest is to just call the -filter directly:: +filter directly: + +.. code-block:: python stream = noop(stream) The ``Stream`` class also provides a ``filter()`` method, which takes an -arbitrary number of filter callables and applies them all:: +arbitrary number of filter callables and applies them all: + +.. code-block:: python stream = stream.filter(noop) Finally, filters can also be applied using the *bitwise or* operator (``|``), -which allows a syntax similar to pipes on Unix shells:: +which allows a syntax similar to pipes on Unix shells: + +.. code-block:: python stream = stream | noop @@ -90,17 +100,23 @@ ``genshi.filters``. It processes a stream of HTML markup, and strips out any potentially dangerous constructs, such as Javascript event handlers. ``HTMLSanitizer`` is not a function, but rather a class that implements -``__call__``, which means instances of the class are callable:: +``__call__``, which means instances of the class are callable: + +.. code-block:: python stream = stream | HTMLSanitizer() Both the ``filter()`` method and the pipe operator allow easy chaining of -filters:: +filters: + +.. code-block:: python from genshi.filters import HTMLSanitizer stream = stream.filter(noop, HTMLSanitizer()) -That is equivalent to:: +That is equivalent to: + +.. code-block:: python stream = stream | noop | HTMLSanitizer() @@ -121,7 +137,9 @@ (which are basically unicode strings that are considered safe for output on the web). The latter returns a single string, by default UTF-8 encoded. -Here's the output from ``serialize()``:: +Here's the output from ``serialize()``: + +.. code-block:: pycon >>> for output in stream.serialize(): ... print `output` @@ -135,14 +153,18 @@ '> '> -And here's the output from ``render()``:: +And here's the output from ``render()``: + +.. code-block:: pycon >>> print stream.render()

-This will produce the following output:: +This will produce the following output: + +.. code-block:: genshi

Hello, world! @@ -229,7 +249,9 @@ ============== By default, Genshi allows you to access variables that are not defined, without -raising a ``NameError`` exception as regular Python code would:: +raising a ``NameError`` exception as regular Python code would: + +.. code-block:: pycon >>> from genshi.template import MarkupTemplate >>> tmpl = MarkupTemplate('

${doh}

') @@ -237,7 +259,9 @@

You *will* however get an exception if you try to call an undefined variable, or -do anything else with it, such as accessing its attributes:: +do anything else with it, such as accessing its attributes: + +.. code-block:: pycon >>> from genshi.template import MarkupTemplate >>> tmpl = MarkupTemplate('

${doh.oops}

') @@ -247,7 +271,9 @@ UndefinedError: "doh" not defined If you need to know whether a variable is defined, you can check its type -against the ``Undefined`` class, for example in a conditional directive:: +against the ``Undefined`` class, for example in a conditional directive: + +.. code-block:: pycon >>> from genshi.template import MarkupTemplate >>> tmpl = MarkupTemplate('

${type(doh) is not Undefined}

') @@ -266,7 +292,9 @@ This mode can be chosen by passing the ``lookup='strict'`` keyword argument to the template initializer, or by passing the ``variable_lookup='strict'`` keyword -argument to the ``TemplateLoader`` initializer:: +argument to the ``TemplateLoader`` initializer: + +.. code-block:: pycon >>> from genshi.template import MarkupTemplate >>> tmpl = MarkupTemplate('

${doh}

', lookup='strict') diff --git a/doc/text-templates.txt b/doc/text-templates.txt --- a/doc/text-templates.txt +++ b/doc/text-templates.txt @@ -57,7 +57,9 @@ ``#if`` --------- -The content is only rendered if the expression evaluates to a truth value:: +The content is only rendered if the expression evaluates to a truth value: + +.. code-block:: genshitext #if foo ${bar} @@ -82,7 +84,9 @@ no ``#when`` branch matches, the ``#otherwise`` branch is be rendered. If the ``#choose`` directive has no argument the nested ``#when`` directives -will be tested for truth:: +will be tested for truth: + +.. code-block:: genshitext The answer is: #choose @@ -103,7 +107,9 @@ 1 If the ``#choose`` does have an argument, the nested ``#when`` directives will -be tested for equality to the parent ``#choose`` value:: +be tested for equality to the parent ``#choose`` value: + +.. code-block:: genshitext The answer is: #choose 1 @@ -132,7 +138,9 @@ ``#for`` ---------- -The content is repeated for every item in an iterable:: +The content is repeated for every item in an iterable: + +.. code-block:: genshitext Your items: #for item in items @@ -158,7 +166,9 @@ The ``#def`` directive can be used to create macros, i.e. snippets of template text that have a name and optionally some parameters, and that can be inserted -in other places:: +in other places: + +.. code-block:: genshitext #def greeting(name) Hello, ${name}! @@ -172,7 +182,9 @@ Hello, everyone else! If a macro doesn't require parameters, it can be defined as well as called -without the parenthesis. For example:: +without the parenthesis. For example: + +.. code-block:: genshitext #def greeting Hello, world! @@ -198,7 +210,9 @@ than once, and that actually results in a database query, assigning the results to a variable using this directive would probably help. -For example:: +For example: + +.. code-block:: genshitext Magic numbers! #with y=7; z=x+10 diff --git a/doc/xml-templates.txt b/doc/xml-templates.txt --- a/doc/xml-templates.txt +++ b/doc/xml-templates.txt @@ -42,7 +42,9 @@ conditionals and looping, among others. To use directives in a template, the namespace must be declared, which is -usually done on the root element:: +usually done on the root element: + +.. code-block:: genshi -This is basically equivalent to the following:: +This is basically equivalent to the following: + +.. code-block:: genshi ${bar}

Given the data ``foo=True`` and ``bar='Hello'`` in the template context, this -would produce:: +would produce: + +.. code-block:: html

Hello

-This directive can also be used as an element:: +This directive can also be used as an element: + +.. code-block:: genshi

@@ -129,7 +141,9 @@ if no ``py:when`` branch matches, the ``py:otherwise`` branch is rendered. If the ``py:choose`` directive is empty the nested ``py:when`` directives will -be tested for truth:: +be tested for truth: + +.. code-block:: genshi

0 @@ -137,14 +151,18 @@ 2

-This would produce the following output:: +This would produce the following output: + +.. code-block:: html

If the ``py:choose`` directive contains an expression the nested ``py:when`` -directives will be tested for equality to the parent ``py:choose`` value:: +directives will be tested for equality to the parent ``py:choose`` value: + +.. code-block:: genshi

0 @@ -152,7 +170,9 @@ 2

-This would produce the following output:: +This would produce the following output: + +.. code-block:: html

1 @@ -167,19 +187,25 @@ ``py:for`` ---------- -The element is repeated for every item in an iterable:: +The element is repeated for every item in an iterable: + +.. code-block:: genshi

${item}

-Given ``items=[1, 2, 3]`` in the context data, this would produce:: +Given ``items=[1, 2, 3]`` in the context data, this would produce: + +.. code-block:: html

-This directive can also be used as an element:: +This directive can also be used as an element: + +.. code-block:: genshi

@@ -199,7 +225,9 @@ The ``py:def`` directive can be used to create macros, i.e. snippets of template code that have a name and optionally some parameters, and that can be -inserted in other places:: +inserted in other places: + +.. code-block:: genshi

@@ -209,7 +237,9 @@ ${greeting('everyone else')}

-The above would be rendered to:: +The above would be rendered to: + +.. code-block:: html

@@ -221,7 +251,9 @@

If a macro doesn't require parameters, it can be defined without the -parenthesis. For example:: +parenthesis. For example: + +.. code-block:: genshi

@@ -230,7 +262,9 @@ ${greeting()}

-The above would be rendered to:: +The above would be rendered to: + +.. code-block:: html

@@ -238,7 +272,9 @@

-This directive can also be used as an element:: +This directive can also be used as an element: + +.. code-block:: genshi

@@ -258,7 +294,9 @@ content. For example, the match template defined in the following template matches any -element with the tag name “greeting”:: +element with the tag name “greeting”: + +.. code-block:: genshi

@@ -267,7 +305,9 @@

-This would result in the following output:: +This would result in the following output: + +.. code-block:: html

@@ -282,7 +322,9 @@ .. _`Using XPath`: streams.html#using-xpath -This directive can also be used as an element:: +This directive can also be used as an element: + +.. code-block:: genshi

@@ -306,19 +348,25 @@ than once, and that actually results in a database query, assigning the results to a variable using this directive would probably help. -For example:: +For example: + +.. code-block:: genshi

$x $y $z

-Given ``x=42`` in the context data, this would produce:: +Given ``x=42`` in the context data, this would produce: + +.. code-block:: html

42 7 52

-This directive can also be used as an element:: +This directive can also be used as an element: + +.. code-block:: genshi

$x $y $z @@ -338,21 +386,27 @@ ``py:attrs`` ------------ -This directive adds, modifies or removes attributes from the element:: +This directive adds, modifies or removes attributes from the element: + +.. code-block:: genshi

Given ``foo={'class': 'collapse'}`` in the template context, this would -produce:: +produce: + +.. code-block:: html

Attributes with the value ``None`` are omitted, so given ``foo={'class': None}`` -in the context for the same template this would produce:: +in the context for the same template this would produce: + +.. code-block:: html

Hello

Hello

Bye @@ -410,13 +472,17 @@ This directive conditionally strips the top-level element from the output. When the value of the ``py:strip`` attribute evaluates to ``True``, the element is -stripped from the output:: +stripped from the output: + +.. code-block:: genshi

foo

-This would be rendered as:: +This would be rendered as: + +.. code-block:: html

foo @@ -462,7 +528,9 @@ For this, you need to declare the XInclude namespace (commonly bound to the prefix “xi”) and use the ```` element where you want the external -file to be pulled in:: +file to be pulled in: + +.. code-block:: genshi @@ -497,7 +567,9 @@ Incudes in Genshi are fully dynamic: Just like normal attributes, the `href` attribute accepts expressions, and directives_ can be used on the ```` element just as on any other element, meaning you can do -things like conditional includes:: +things like conditional includes: + +.. code-block:: genshi @@ -509,17 +581,23 @@ Comments -------- -Normal XML/HTML comment syntax can be used in templates:: +Normal XML/HTML comment syntax can be used in templates: + +.. code-block:: genshi However, such comments get passed through the processing pipeline and are by default included in the final output. If that's not desired, prefix the comment -text with an exclamation mark:: +text with an exclamation mark: + +.. code-block:: genshi Note that it does not matter whether there's whitespace before or after the -exclamation mark, so the above could also be written as follows:: +exclamation mark, so the above could also be written as follows: + +.. code-block:: genshi diff --git a/doc/xpath.txt b/doc/xpath.txt --- a/doc/xpath.txt +++ b/doc/xpath.txt @@ -62,24 +62,25 @@ Querying Streams ---------------- -:: - - from genshi.input import XML +The ``Stream`` class provides a ``select(path)`` function that can be used to +retrieve subsets of the stream: - doc = XML(''' - - -

Foo

- - -

Bar

- - - ''') - print doc.select('items/item[@status="closed"]/summary/text()') +.. code-block:: pycon -This would result in the following output:: - + >>> from genshi.input import XML + + >>> doc = XML(''' + ... + ... + ...

Foo

+ ... + ... + ...

Bar

+ ... + ... + ... ''') + + >>> print doc.select('items/item[@status="closed"]/summary/text()') Bar diff --git a/setup.py b/setup.py --- a/setup.py +++ b/setup.py @@ -35,9 +35,29 @@ def run(self): from docutils.core import publish_cmdline + from docutils.nodes import raw + from docutils.parsers import rst + docutils_conf = os.path.join('doc', 'docutils.conf') epydoc_conf = os.path.join('doc', 'epydoc.conf') + try: + from pygments import highlight + from pygments.lexers import get_lexer_by_name + from pygments.formatters import HtmlFormatter + + def code_block(name, arguments, options, content, lineno, + content_offset, block_text, state, state_machine): + lexer = get_lexer_by_name(arguments[0]) + html = highlight('\n'.join(content), lexer, HtmlFormatter()) + return [raw('', html, format='html')] + code_block.arguments = (1, 0, 0) + code_block.options = {'language' : rst.directives.unchanged} + code_block.content = 1 + rst.directives.register_directive('code-block', code_block) + except ImportError: + print 'Pygments not installed, syntax highlighting disabled' + for source in glob('doc/*.txt'): dest = os.path.splitext(source)[0] + '.html' if not os.path.exists(dest) or \ @@ -58,7 +78,6 @@ ] cli.cli() sys.argv[1:] = old_argv - except ImportError: print 'epydoc not installed, skipping API documentation.'

Hello, $name!

Hello, world!