Mercurial > genshi > mirror

annotate doc/builder.txt @ 382:2682dabbcd04 trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
* Added documentation for the various stream event kinds. * Move generation of HTML documentation into a custom distutils command, run by `setup.py build_doc` * Added verification of doctest snippets in documentation, which can be run by `setup.py test_doc` * Fixed `repr` of `Markup` instances.
author cmlenz
date Fri, 01 Dec 2006 23:43:59 +0000
parents 41107d1ba1c8
children
rev   line source
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
1 .. -*- mode: rst; encoding: utf-8 -*-
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
2
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
3 ==================================
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
4 Generating Markup Programmatically
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
5 ==================================
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
6
230
84168828b074 Renamed Markup to Genshi in repository.
cmlenz
parents: 226
diff changeset
7 Genshi provides a ``builder`` module which lets you generate markup from Python
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
8 code using a very simple syntax. The main entry point to the ``builder`` module
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
9 is the ``tag`` object (which is actually an instance of the ``ElementFactory``
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
10 class). You should rarely (if ever) need to directly import and use any of the
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
11 other classes in the ``builder`` module.
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
12
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
13
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
14 .. contents:: Contents
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
15 :depth: 2
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
16 .. sectnum::
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
17
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
18
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
19 Creating Elements
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
20 =================
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
21
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
22 Elements can be created through the `tag` object using attribute access, for
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
23 example::
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
24
230
84168828b074 Renamed Markup to Genshi in repository.
cmlenz
parents: 226
diff changeset
25 >>> from genshi.builder import tag
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
26 >>> doc = tag.p('Some text and ', tag.a('a link', href='http://example.org/'), '.')
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
27 >>> doc
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
28 <Element "p">
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
29
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
30 This produces an ``Element`` instance which can be further modified to add child
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
31 nodes and attributes. This is done by “calling” the element: positional
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
32 arguments are added as child nodes (alternatively, the ``append`` method can be
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
33 used for that purpose), whereas keywords arguments are added as attributes::
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
34
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
35 >>> doc(tag.br)
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
36 <Element "p">
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
37 >>> print doc
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
38 <p>Some text and <a href="http://example.org/">a link</a>.<br/></p>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
39
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
40 If an attribute name collides with a Python keyword, simply append an underscore
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
41 to the name::
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
42
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
43 >>> doc(class_='intro')
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
44 <Element "p">
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
45 >>> print doc
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
46 <p class="intro">Some text and <a href="http://example.org/">a link</a>.<br/></p>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
47
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
48 As shown above, an ``Element`` can easily be directly rendered to XML text by
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
49 printing it or using the Python ``str()`` function. This is basically a
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
50 shortcut for converting the ``Element`` to a stream and serializing that
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
51 stream::
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
52
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
53 >>> stream = doc.generate()
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
54 >>> stream
382
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 235
diff changeset
55 <genshi.core.Stream object at ...>
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
56 >>> print stream
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
57 <p class="intro">Some text and <a href="http://example.org/">a link</a>.<br/></p>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
58
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
59
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
60 Creating Fragments
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
61 ==================
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
62
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
63 The ``tag`` object also allows creating “fragments”, which are basically lists
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
64 of nodes (elements or text) that don't have a parent element. This can be useful
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
65 for creating snippets of markup that are attached to a parent element later (for
235
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
66 example in a template). Fragments are created by calling the ``tag`` object::
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
67
382
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 235
diff changeset
68 >>> fragment = tag('Hello, ', tag.em('world'), '!')
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
69 >>> fragment
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
70 <Fragment>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
71 >>> print fragment
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
72 Hello, <em>world</em>!
Copyright (C) 2012-2017 Edgewall Software