Mercurial > hg > decoupage

annotate README.txt @ 40:89f7a8ca965c

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
add arguments to transformers....configparser is somewhat retarded about capitalization so im going to be somewhat retarded here rather than google for how to fix right now. lame
author Jeff Hammel <jhammel@mozilla.com>
date Wed, 30 Jun 2010 22:33:26 -0700
parents 9ba237db4cde
children 5330cd62e179
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
0
fa2005f769eb adding decoupage from http://my-svn.assembla.com/svn/arbez/decoupage r355
k0s <k0scist@gmail.com>
parents:
diff changeset
1 decoupage
fa2005f769eb adding decoupage from http://my-svn.assembla.com/svn/arbez/decoupage r355
k0s <k0scist@gmail.com>
parents:
diff changeset
2 =========
fa2005f769eb adding decoupage from http://my-svn.assembla.com/svn/arbez/decoupage r355
k0s <k0scist@gmail.com>
parents:
diff changeset
3
fa2005f769eb adding decoupage from http://my-svn.assembla.com/svn/arbez/decoupage r355
k0s <k0scist@gmail.com>
parents:
diff changeset
4 what is it?
fa2005f769eb adding decoupage from http://my-svn.assembla.com/svn/arbez/decoupage r355
k0s <k0scist@gmail.com>
parents:
diff changeset
5 -----------
fa2005f769eb adding decoupage from http://my-svn.assembla.com/svn/arbez/decoupage r355
k0s <k0scist@gmail.com>
parents:
diff changeset
6
fa2005f769eb adding decoupage from http://my-svn.assembla.com/svn/arbez/decoupage r355
k0s <k0scist@gmail.com>
parents:
diff changeset
7 decoupage is a static file server that allows for index pages
fa2005f769eb adding decoupage from http://my-svn.assembla.com/svn/arbez/decoupage r355
k0s <k0scist@gmail.com>
parents:
diff changeset
8 configurable with genshi templates and .ini files. I mainly wrote it
fa2005f769eb adding decoupage from http://my-svn.assembla.com/svn/arbez/decoupage r355
k0s <k0scist@gmail.com>
parents:
diff changeset
9 because i was tired of using apache for serving my website and
18
ebc1a802f9b8 update documentation
k0s <k0scist@gmail.com>
parents: 0
diff changeset
10 generating index.html files by hand. Decoupage provides views into
ebc1a802f9b8 update documentation
k0s <k0scist@gmail.com>
parents: 0
diff changeset
11 the filesystem.
ebc1a802f9b8 update documentation
k0s <k0scist@gmail.com>
parents: 0
diff changeset
12
0
fa2005f769eb adding decoupage from http://my-svn.assembla.com/svn/arbez/decoupage r355
k0s <k0scist@gmail.com>
parents:
diff changeset
13
fa2005f769eb adding decoupage from http://my-svn.assembla.com/svn/arbez/decoupage r355
k0s <k0scist@gmail.com>
parents:
diff changeset
14
fa2005f769eb adding decoupage from http://my-svn.assembla.com/svn/arbez/decoupage r355
k0s <k0scist@gmail.com>
parents:
diff changeset
15 how do i use it?
fa2005f769eb adding decoupage from http://my-svn.assembla.com/svn/arbez/decoupage r355
k0s <k0scist@gmail.com>
parents:
diff changeset
16 ----------------
fa2005f769eb adding decoupage from http://my-svn.assembla.com/svn/arbez/decoupage r355
k0s <k0scist@gmail.com>
parents:
diff changeset
17
fa2005f769eb adding decoupage from http://my-svn.assembla.com/svn/arbez/decoupage r355
k0s <k0scist@gmail.com>
parents:
diff changeset
18 Set up a `paste <http://pythonpaste.org>`_ .ini file that specifies the
fa2005f769eb adding decoupage from http://my-svn.assembla.com/svn/arbez/decoupage r355
k0s <k0scist@gmail.com>
parents:
diff changeset
19 directory to serve (``decoupage.directory``) and, optionally, a
fa2005f769eb adding decoupage from http://my-svn.assembla.com/svn/arbez/decoupage r355
k0s <k0scist@gmail.com>
parents:
diff changeset
20 configuration file .ini file (``decoupage.configuraton``) which
fa2005f769eb adding decoupage from http://my-svn.assembla.com/svn/arbez/decoupage r355
k0s <k0scist@gmail.com>
parents:
diff changeset
21 specifies the labels for the files based on directory. An example of a
fa2005f769eb adding decoupage from http://my-svn.assembla.com/svn/arbez/decoupage r355
k0s <k0scist@gmail.com>
parents:
diff changeset
22 `paste <http://pythonpaste.org>`_ .ini file is in
fa2005f769eb adding decoupage from http://my-svn.assembla.com/svn/arbez/decoupage r355
k0s <k0scist@gmail.com>
parents:
diff changeset
23 ``decoupage.ini``. Note the ``[app:decoupage]`` section::
fa2005f769eb adding decoupage from http://my-svn.assembla.com/svn/arbez/decoupage r355
k0s <k0scist@gmail.com>
parents:
diff changeset
24
fa2005f769eb adding decoupage from http://my-svn.assembla.com/svn/arbez/decoupage r355
k0s <k0scist@gmail.com>
parents:
diff changeset
25 [app:decoupage]
fa2005f769eb adding decoupage from http://my-svn.assembla.com/svn/arbez/decoupage r355
k0s <k0scist@gmail.com>
parents:
diff changeset
26 paste.app_factory = decoupage.factory:factory
fa2005f769eb adding decoupage from http://my-svn.assembla.com/svn/arbez/decoupage r355
k0s <k0scist@gmail.com>
parents:
diff changeset
27 decoupage.directory = %(here)s/example
fa2005f769eb adding decoupage from http://my-svn.assembla.com/svn/arbez/decoupage r355
k0s <k0scist@gmail.com>
parents:
diff changeset
28 decoupage.configuration = %(here)s/example.ini
fa2005f769eb adding decoupage from http://my-svn.assembla.com/svn/arbez/decoupage r355
k0s <k0scist@gmail.com>
parents:
diff changeset
29
fa2005f769eb adding decoupage from http://my-svn.assembla.com/svn/arbez/decoupage r355
k0s <k0scist@gmail.com>
parents:
diff changeset
30 The labels for files are in ``example.ini``, specified by sections as
fa2005f769eb adding decoupage from http://my-svn.assembla.com/svn/arbez/decoupage r355
k0s <k0scist@gmail.com>
parents:
diff changeset
31 directories::
fa2005f769eb adding decoupage from http://my-svn.assembla.com/svn/arbez/decoupage r355
k0s <k0scist@gmail.com>
parents:
diff changeset
32
fa2005f769eb adding decoupage from http://my-svn.assembla.com/svn/arbez/decoupage r355
k0s <k0scist@gmail.com>
parents:
diff changeset
33 [/]
fa2005f769eb adding decoupage from http://my-svn.assembla.com/svn/arbez/decoupage r355
k0s <k0scist@gmail.com>
parents:
diff changeset
34 foo.txt = a file about cats
fa2005f769eb adding decoupage from http://my-svn.assembla.com/svn/arbez/decoupage r355
k0s <k0scist@gmail.com>
parents:
diff changeset
35
fa2005f769eb adding decoupage from http://my-svn.assembla.com/svn/arbez/decoupage r355
k0s <k0scist@gmail.com>
parents:
diff changeset
36 [/cats]
fa2005f769eb adding decoupage from http://my-svn.assembla.com/svn/arbez/decoupage r355
k0s <k0scist@gmail.com>
parents:
diff changeset
37 lilly.txt = lilly
fa2005f769eb adding decoupage from http://my-svn.assembla.com/svn/arbez/decoupage r355
k0s <k0scist@gmail.com>
parents:
diff changeset
38 hobbes.txt = a file about Hobbes
fa2005f769eb adding decoupage from http://my-svn.assembla.com/svn/arbez/decoupage r355
k0s <k0scist@gmail.com>
parents:
diff changeset
39
fa2005f769eb adding decoupage from http://my-svn.assembla.com/svn/arbez/decoupage r355
k0s <k0scist@gmail.com>
parents:
diff changeset
40 You can specify the entire layout from here. Alternately, you can
fa2005f769eb adding decoupage from http://my-svn.assembla.com/svn/arbez/decoupage r355
k0s <k0scist@gmail.com>
parents:
diff changeset
41 have an ``index.ini`` in a directory which, if present, overrides the
fa2005f769eb adding decoupage from http://my-svn.assembla.com/svn/arbez/decoupage r355
k0s <k0scist@gmail.com>
parents:
diff changeset
42 default configuration. Such a file is in the ``fleem`` subdirectory
fa2005f769eb adding decoupage from http://my-svn.assembla.com/svn/arbez/decoupage r355
k0s <k0scist@gmail.com>
parents:
diff changeset
43 of ``example``::
fa2005f769eb adding decoupage from http://my-svn.assembla.com/svn/arbez/decoupage r355
k0s <k0scist@gmail.com>
parents:
diff changeset
44
fa2005f769eb adding decoupage from http://my-svn.assembla.com/svn/arbez/decoupage r355
k0s <k0scist@gmail.com>
parents:
diff changeset
45 /template = index.html
fa2005f769eb adding decoupage from http://my-svn.assembla.com/svn/arbez/decoupage r355
k0s <k0scist@gmail.com>
parents:
diff changeset
46 fleem.txt = some fleem for ya
fa2005f769eb adding decoupage from http://my-svn.assembla.com/svn/arbez/decoupage r355
k0s <k0scist@gmail.com>
parents:
diff changeset
47
fa2005f769eb adding decoupage from http://my-svn.assembla.com/svn/arbez/decoupage r355
k0s <k0scist@gmail.com>
parents:
diff changeset
48 Try it out! Install decoupage and run ``paster serve decoupage.ini``
fa2005f769eb adding decoupage from http://my-svn.assembla.com/svn/arbez/decoupage r355
k0s <k0scist@gmail.com>
parents:
diff changeset
49 and point your browser to the URL it gives you.
fa2005f769eb adding decoupage from http://my-svn.assembla.com/svn/arbez/decoupage r355
k0s <k0scist@gmail.com>
parents:
diff changeset
50
fa2005f769eb adding decoupage from http://my-svn.assembla.com/svn/arbez/decoupage r355
k0s <k0scist@gmail.com>
parents:
diff changeset
51
fa2005f769eb adding decoupage from http://my-svn.assembla.com/svn/arbez/decoupage r355
k0s <k0scist@gmail.com>
parents:
diff changeset
52 how do i do more with decoupage?
fa2005f769eb adding decoupage from http://my-svn.assembla.com/svn/arbez/decoupage r355
k0s <k0scist@gmail.com>
parents:
diff changeset
53 --------------------------------
fa2005f769eb adding decoupage from http://my-svn.assembla.com/svn/arbez/decoupage r355
k0s <k0scist@gmail.com>
parents:
diff changeset
54
fa2005f769eb adding decoupage from http://my-svn.assembla.com/svn/arbez/decoupage r355
k0s <k0scist@gmail.com>
parents:
diff changeset
55 Since filenames can't start with a ``/`` (just try it!), the
fa2005f769eb adding decoupage from http://my-svn.assembla.com/svn/arbez/decoupage r355
k0s <k0scist@gmail.com>
parents:
diff changeset
56 functionality of decoupage may be extended with ``/`` commands in a
fa2005f769eb adding decoupage from http://my-svn.assembla.com/svn/arbez/decoupage r355
k0s <k0scist@gmail.com>
parents:
diff changeset
57 section. This is done by adding a setuptools ``entry_point`` to
fa2005f769eb adding decoupage from http://my-svn.assembla.com/svn/arbez/decoupage r355
k0s <k0scist@gmail.com>
parents:
diff changeset
58 ``[decoupage.formatters]``. See the decoupage ``setup.py`` and
18
ebc1a802f9b8 update documentation
k0s <k0scist@gmail.com>
parents: 0
diff changeset
59 ``decoupage.formatters`` for examples. For instance,
ebc1a802f9b8 update documentation
k0s <k0scist@gmail.com>
parents: 0
diff changeset
60
ebc1a802f9b8 update documentation
k0s <k0scist@gmail.com>
parents: 0
diff changeset
61 Running `decoupage-formatters` from the command line gives the list of
ebc1a802f9b8 update documentation
k0s <k0scist@gmail.com>
parents: 0
diff changeset
62 formatters that are available (which are pluggable setuptools extension points
ebc1a802f9b8 update documentation
k0s <k0scist@gmail.com>
parents: 0
diff changeset
63 at [decoupage.formatters]). For example: /include = site.html could
ebc1a802f9b8 update documentation
k0s <k0scist@gmail.com>
parents: 0
diff changeset
64 include the site.html genshi template at the top of the body.
ebc1a802f9b8 update documentation
k0s <k0scist@gmail.com>
parents: 0
diff changeset
65
27
9e86c5cb111a minor documentation updates
k0s <k0scist@gmail.com>
parents: 18
diff changeset
66 Formatters:
9e86c5cb111a minor documentation updates
k0s <k0scist@gmail.com>
parents: 18
diff changeset
67
28
fc1c479296c3 more docmentation updates
k0s <k0scist@gmail.com>
parents: 27
diff changeset
68 sort:
fc1c479296c3 more docmentation updates
k0s <k0scist@gmail.com>
parents: 27
diff changeset
69 determines how to sort the files in a directory;
fc1c479296c3 more docmentation updates
k0s <k0scist@gmail.com>
parents: 27
diff changeset
70 right now only by case-insensitive alphabetically
fc1c479296c3 more docmentation updates
k0s <k0scist@gmail.com>
parents: 27
diff changeset
71 * reverse : reverse the order of the sorting
fc1c479296c3 more docmentation updates
k0s <k0scist@gmail.com>
parents: 27
diff changeset
72
18
ebc1a802f9b8 update documentation
k0s <k0scist@gmail.com>
parents: 0
diff changeset
73 all:
ebc1a802f9b8 update documentation
k0s <k0scist@gmail.com>
parents: 0
diff changeset
74 only pass files of a certain pattern;
ebc1a802f9b8 update documentation
k0s <k0scist@gmail.com>
parents: 0
diff changeset
75 the inverse of ignore
ebc1a802f9b8 update documentation
k0s <k0scist@gmail.com>
parents: 0
diff changeset
76 calling all with no arguments means only files with descriptions
ebc1a802f9b8 update documentation
k0s <k0scist@gmail.com>
parents: 0
diff changeset
77 are used
ebc1a802f9b8 update documentation
k0s <k0scist@gmail.com>
parents: 0
diff changeset
78
28
fc1c479296c3 more docmentation updates
k0s <k0scist@gmail.com>
parents: 27
diff changeset
79 title:
fc1c479296c3 more docmentation updates
k0s <k0scist@gmail.com>
parents: 27
diff changeset
80 splits a description into a title and a description via a
fc1c479296c3 more docmentation updates
k0s <k0scist@gmail.com>
parents: 27
diff changeset
81 separator in
fc1c479296c3 more docmentation updates
k0s <k0scist@gmail.com>
parents: 27
diff changeset
82 the description. The template will now have an additional
fc1c479296c3 more docmentation updates
k0s <k0scist@gmail.com>
parents: 27
diff changeset
83 variable,
fc1c479296c3 more docmentation updates
k0s <k0scist@gmail.com>
parents: 27
diff changeset
84 'title', per file
fc1c479296c3 more docmentation updates
k0s <k0scist@gmail.com>
parents: 27
diff changeset
85 Arguments:
fc1c479296c3 more docmentation updates
k0s <k0scist@gmail.com>
parents: 27
diff changeset
86 * separator: what separator to use (':' by default)
fc1c479296c3 more docmentation updates
k0s <k0scist@gmail.com>
parents: 27
diff changeset
87
fc1c479296c3 more docmentation updates
k0s <k0scist@gmail.com>
parents: 27
diff changeset
88 describe:
fc1c479296c3 more docmentation updates
k0s <k0scist@gmail.com>
parents: 27
diff changeset
89 obtain the description from the filename
fc1c479296c3 more docmentation updates
k0s <k0scist@gmail.com>
parents: 27
diff changeset
90 the file extension (if any) will be dropped and
fc1c479296c3 more docmentation updates
k0s <k0scist@gmail.com>
parents: 27
diff changeset
91 spaces will be substituted for underscores
fc1c479296c3 more docmentation updates
k0s <k0scist@gmail.com>
parents: 27
diff changeset
92
fc1c479296c3 more docmentation updates
k0s <k0scist@gmail.com>
parents: 27
diff changeset
93 ignore:
fc1c479296c3 more docmentation updates
k0s <k0scist@gmail.com>
parents: 27
diff changeset
94 ignore files of a glob patterns.
fc1c479296c3 more docmentation updates
k0s <k0scist@gmail.com>
parents: 27
diff changeset
95 These files will not be linked to in the template.
fc1c479296c3 more docmentation updates
k0s <k0scist@gmail.com>
parents: 27
diff changeset
96 e.g. /ignore = .* *.pdf # don't list dotfiles and PDFs
fc1c479296c3 more docmentation updates
k0s <k0scist@gmail.com>
parents: 27
diff changeset
97
18
ebc1a802f9b8 update documentation
k0s <k0scist@gmail.com>
parents: 0
diff changeset
98 include: include a file at the top of the body
28
fc1c479296c3 more docmentation updates
k0s <k0scist@gmail.com>
parents: 27
diff changeset
99 css: specify CSS used (whitespace separated list)
18
ebc1a802f9b8 update documentation
k0s <k0scist@gmail.com>
parents: 0
diff changeset
100
27
9e86c5cb111a minor documentation updates
k0s <k0scist@gmail.com>
parents: 18
diff changeset
101 Decoupage also makes use of other special intrinsic keywords:
9e86c5cb111a minor documentation updates
k0s <k0scist@gmail.com>
parents: 18
diff changeset
102
28
fc1c479296c3 more docmentation updates
k0s <k0scist@gmail.com>
parents: 27
diff changeset
103 formatters: ordered list of formatters to apply
fc1c479296c3 more docmentation updates
k0s <k0scist@gmail.com>
parents: 27
diff changeset
104
fc1c479296c3 more docmentation updates
k0s <k0scist@gmail.com>
parents: 27
diff changeset
105 inherit: inherit configuration from a certain directory (instead of
fc1c479296c3 more docmentation updates
k0s <k0scist@gmail.com>
parents: 27
diff changeset
106 the parent
fc1c479296c3 more docmentation updates
k0s <k0scist@gmail.com>
parents: 27
diff changeset
107
fc1c479296c3 more docmentation updates
k0s <k0scist@gmail.com>
parents: 27
diff changeset
108 transform: a list of transformers for contenttransformer
36
9ba237db4cde adding TODO items
k0s <k0scist@gmail.com>
parents: 29
diff changeset
109
9ba237db4cde adding TODO items
k0s <k0scist@gmail.com>
parents: 29
diff changeset
110
9ba237db4cde adding TODO items
k0s <k0scist@gmail.com>
parents: 29
diff changeset
111 TODO
9ba237db4cde adding TODO items
k0s <k0scist@gmail.com>
parents: 29
diff changeset
112 ----
9ba237db4cde adding TODO items
k0s <k0scist@gmail.com>
parents: 29
diff changeset
113
9ba237db4cde adding TODO items
k0s <k0scist@gmail.com>
parents: 29
diff changeset
114 * allow transformers to be configurable on a per-directory basis
9ba237db4cde adding TODO items
k0s <k0scist@gmail.com>
parents: 29
diff changeset
115 * add a ``?format=rss`` query string argument
9ba237db4cde adding TODO items
k0s <k0scist@gmail.com>
parents: 29
diff changeset
116 * add a ``?template=foo.html`` query string argument