Mercurial > hg > decoupage

annotate README.txt @ 22:a8d36caa8f09

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
add formatter
author egj@socialplanning.org
date Mon, 04 Jan 2010 03:28:41 +0000
parents ebc1a802f9b8
children 9e86c5cb111a
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
ebc1a802f9b8 update documentation
k0s <k0scist@gmail.com>
parents: 0
diff changeset
66 all:
ebc1a802f9b8 update documentation
k0s <k0scist@gmail.com>
parents: 0
diff changeset
67 only pass files of a certain pattern;
ebc1a802f9b8 update documentation
k0s <k0scist@gmail.com>
parents: 0
diff changeset
68 the inverse of ignore
ebc1a802f9b8 update documentation
k0s <k0scist@gmail.com>
parents: 0
diff changeset
69 calling all with no arguments means only files with descriptions
ebc1a802f9b8 update documentation
k0s <k0scist@gmail.com>
parents: 0
diff changeset
70 are used
ebc1a802f9b8 update documentation
k0s <k0scist@gmail.com>
parents: 0
diff changeset
71
ebc1a802f9b8 update documentation
k0s <k0scist@gmail.com>
parents: 0
diff changeset
72 title: splits a description into a title and a description with a
ebc1a802f9b8 update documentation
k0s <k0scist@gmail.com>
parents: 0
diff changeset
73 separator
ebc1a802f9b8 update documentation
k0s <k0scist@gmail.com>
parents: 0
diff changeset
74 describe: substitute the description for the filename
ebc1a802f9b8 update documentation
k0s <k0scist@gmail.com>
parents: 0
diff changeset
75 ignore: ignore files of a certain pattern
ebc1a802f9b8 update documentation
k0s <k0scist@gmail.com>
parents: 0
diff changeset
76 include: include a file at the top of the body
ebc1a802f9b8 update documentation
k0s <k0scist@gmail.com>
parents: 0
diff changeset
77 css: specify CSS
ebc1a802f9b8 update documentation
k0s <k0scist@gmail.com>
parents: 0
diff changeset
78