Mercurial > hg > decoupage

annotate README.txt @ 64:613ffeec2be5

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
return exceptions rather than just raise them; needed for wsgiref and who knows what other servers
author Jeff Hammel <jhammel@mozilla.com>
date Wed, 15 Dec 2010 09:30:32 -0800
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