Mercurial > piecrust2

annotate docs/pages/code.md @ 415:0e9a94b7fdfa

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
bake: Improve bake record information. * Store things in the bake record that require less interaction between the master process and the workers. For instance, don't store the paginator object in the render pass info -- instead, just store whether pagination was used, and whether it had more items. * Simplify information passing between workers and bake passes by saving the rendering info to the JSON cache. This means the "render first sub" job doesn't have to return anything except errors now. * Add more performance counter info.
author Ludovic Chabant <ludovic@chabant.com>
date Sat, 20 Jun 2015 19:23:16 -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