Mercurial > piecrust2

annotate docs/pages/code.md @ 357:3a496ffbb898 2.0.0a7

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
docs: Add documentation for importing content from other engines.
author Ludovic Chabant <ludovic@chabant.com>
date Mon, 20 Apr 2015 22:35:10 -0700
parents 9188b362069e
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
243
26e59f837558 docs: Add embryo of a documentation website.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
1 ---
26e59f837558 docs: Add embryo of a documentation website.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
2 title: Code
26e59f837558 docs: Add embryo of a documentation website.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
3 header_class: code
26e59f837558 docs: Add embryo of a documentation website.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
4 ---
26e59f837558 docs: Add embryo of a documentation website.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
5
313
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
6 ## PieCrust plugins
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
7
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
8 To create a PieCrust plugin, you need to do a few things:
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
9
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
10 * Create a correct `setuptools` package.
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
11 * Implement a sub-class of `PieCrustPlugin`.
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
12 * Write a couple lines of boilerplate code.
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
13
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
14
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
15 ### Packaging plugins
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
16
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
17 PieCrust plugins are expected to be available on [Pypi][] for better integration
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
18 with `chef` commands. For instance, the `chef plugins list -a` will list all
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
19 PieCrust plugins from Pypi.
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
20
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
21 A PieCrust plugin package must:
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
22
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
23 * Be named `PieCrust-FooBar`, where `FooBar` is the name of the plugin.
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
24 * Have a module named `piecrust_foobar`, which is basically the lower-case
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
25 version of the package name, with an underscore instead of a dash.
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
26
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
27 You can refer to the [`setuptools` documentation][st] for more information.
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
28
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
29
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
30 ### The plugin class
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
31
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
32 A PieCrust plugin is an instance of a class that derives from `PieCrustPlugin`.
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
33 The only required thing you need to override is the name of the plugin:
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
34
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
35 from piecrust.plugins.base import PieCrustPlugin
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
36
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
37 class FooBarPlugin(PieCrustPlugin):
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
38 name = 'FooBar'
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
39
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
40 The plugin class has a whole bunch of functions returning whatever your plugin
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
41 may want to extend: formatters, template engines, `chef` commands, sources, etc.
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
42 Each one of those returns an array of instances or classes, depending on the
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
43 situation.
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
44
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
45 Check the `piecrust.plugins.builtin.BuiltInPlugin` to see how all PieCrust
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
46 functionality is implemented.
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
47
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
48
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
49 ### Boilerplate code
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
50
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
51 Now we have a plugin class, and a Pypi package that PieCrust can find if needed.
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
52 All we need is a way to tell PieCrust how to find your plugin class in that
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
53 package.
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
54
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
55 In the required `piecrust_foobar` module, you need to define a
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
56 `__piecrust_plugin__` global variable that points to your plugin class:
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
57
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
58 __piecrust_plugin__ = FooBarPlugin
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
59
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
60 That's what PieCrust will use to instantiate your plugin.
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
61
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
62
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
63 ### Loading the plugin
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
64
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
65 Now you can add your plugin to a PieCrust website by adding this to the website
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
66 configuration:
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
67
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
68 site:
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
69 plugins: foobar
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
70
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
71 PieCrust will prepend `piecrust_` to each specified plugin name and attempt to
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
72 load that as a module (`import piecrust_foobar`). If this succeeds, it will look
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
73 for a `__piecrust_plugin__` in that module, and expect its value to be a class
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
74 that inherits from `PieCrustPlugin`. If everything's OK, it will instantiate
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
75 that class and query it for various services and components when necessary.
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
76
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
77
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
78 [pypi]: https://pypi.python.org/pypi
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
79 [st]: http://pythonhosted.org/setuptools/
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
80