Mercurial > genshi > mirror
changeset 430:77e99857b351 trunk
Moved the `builder` document into the API docs.
author | cmlenz |
---|---|
date | Thu, 22 Mar 2007 17:14:09 +0000 |
parents | 691dd56c0dd0 |
children | ad01564e87f2 |
files | doc/builder.txt doc/index.txt doc/style/apidoc.css genshi/builder.py |
diffstat | 4 files changed, 57 insertions(+), 75 deletions(-) [+] |
line wrap: on
line diff
deleted file mode 100644 --- a/doc/builder.txt +++ /dev/null @@ -1,72 +0,0 @@ -.. -*- mode: rst; encoding: utf-8 -*- - -================================== -Generating Markup Programmatically -================================== - -Genshi provides a ``builder`` module which lets you generate markup from Python -code using a very simple syntax. The main entry point to the ``builder`` module -is the ``tag`` object (which is actually an instance of the ``ElementFactory`` -class). You should rarely (if ever) need to directly import and use any of the -other classes in the ``builder`` module. - - -.. contents:: Contents - :depth: 2 -.. sectnum:: - - -Creating Elements -================= - -Elements can be created through the `tag` object using attribute access, for -example:: - - >>> from genshi.builder import tag - >>> doc = tag.p('Some text and ', tag.a('a link', href='http://example.org/'), '.') - >>> doc - <Element "p"> - -This produces an ``Element`` instance which can be further modified to add child -nodes and attributes. This is done by “calling” the element: positional -arguments are added as child nodes (alternatively, the ``append`` method can be -used for that purpose), whereas keywords arguments are added as attributes:: - - >>> doc(tag.br) - <Element "p"> - >>> print doc - <p>Some text and <a href="http://example.org/">a link</a>.<br/></p> - -If an attribute name collides with a Python keyword, simply append an underscore -to the name:: - - >>> doc(class_='intro') - <Element "p"> - >>> print doc - <p class="intro">Some text and <a href="http://example.org/">a link</a>.<br/></p> - -As shown above, an ``Element`` can easily be directly rendered to XML text by -printing it or using the Python ``str()`` function. This is basically a -shortcut for converting the ``Element`` to a stream and serializing that -stream:: - - >>> stream = doc.generate() - >>> stream - <genshi.core.Stream object at ...> - >>> print stream - <p class="intro">Some text and <a href="http://example.org/">a link</a>.<br/></p> - - -Creating Fragments -================== - -The ``tag`` object also allows creating “fragments”, which are basically lists -of nodes (elements or text) that don't have a parent element. This can be useful -for creating snippets of markup that are attached to a parent element later (for -example in a template). Fragments are created by calling the ``tag`` object:: - - >>> fragment = tag('Hello, ', tag.em('world'), '!') - >>> fragment - <Fragment> - >>> print fragment - Hello, <em>world</em>!
--- a/doc/index.txt +++ b/doc/index.txt @@ -21,7 +21,6 @@ which is heavily inspired by Kid. * `Markup Streams <streams.html>`_ -* `Generating Markup Programmatically <builder.html>`_ * `Genshi XML Template Language <xml-templates.html>`_ * `Genshi Text Template Language <text-templates.html>`_ * `Using XPath in Genshi <xpath.html>`_
--- a/doc/style/apidoc.css +++ b/doc/style/apidoc.css @@ -110,7 +110,7 @@ .py-string, .variable-string, .variable-quote { color: #093; } .py-comment { color: #06f; font-style: italic; } .py-keyword { color: #00f; } -.py-output { background: #f6f6f0; font-weight: bold; } +.py-output { background: #f6f6f0; color: #666; font-weight: bold; } /* Index */
--- a/genshi/builder.py +++ b/genshi/builder.py @@ -11,7 +11,62 @@ # individuals. For the exact contribution history, see the revision # history and logs, available at http://genshi.edgewall.org/log/. -"""Support for programmatically generating markup streams.""" +"""Support for programmatically generating markup streams from Python code using +a very simple syntax. The main entry point to this module is the `tag` object +(which is actually an instance of the ``ElementFactory`` class). You should +rarely (if ever) need to directly import and use any of the other classes in +this module. + +Elements can be created using the `tag` object using attribute access. For +example: + +>>> doc = tag.p('Some text and ', tag.a('a link', href='http://example.org/'), '.') +>>> doc +<Element "p"> + +This produces an `Element` instance which can be further modified to add child +nodes and attributes. This is done by "calling" the element: positional +arguments are added as child nodes (alternatively, the `Element.append` method +can be used for that purpose), whereas keywords arguments are added as +attributes: + +>>> doc(tag.br) +<Element "p"> +>>> print doc +<p>Some text and <a href="http://example.org/">a link</a>.<br/></p> + +If an attribute name collides with a Python keyword, simply append an underscore +to the name: + +>>> doc(class_='intro') +<Element "p"> +>>> print doc +<p class="intro">Some text and <a href="http://example.org/">a link</a>.<br/></p> + +As shown above, an `Element` can easily be directly rendered to XML text by +printing it or using the Python ``str()`` function. This is basically a +shortcut for converting the `Element` to a stream and serializing that +stream: + +>>> stream = doc.generate() +>>> stream +<genshi.core.Stream object at ...> +>>> print stream +<p class="intro">Some text and <a href="http://example.org/">a link</a>.<br/></p> + + +The `tag` object also allows creating "fragments", which are basically lists +of nodes (elements or text) that don't have a parent element. This can be useful +for creating snippets of markup that are attached to a parent element later (for +example in a template). Fragments are created by calling the `tag` object, which +returns an object of type `Fragment`: + +>>> fragment = tag('Hello, ', tag.em('world'), '!') +>>> fragment +<Fragment> +>>> print fragment +Hello, <em>world</em>! +""" from genshi.core import Attrs, Namespace, QName, Stream, START, END, TEXT