Mercurial > piecrust2
annotate docs/api/02_components/01_commands.md @ 504:20fcadaaf871
docs: Add some API documentation.
At the moment, only the main page for plugin components, and a page for user
commands. Add skeleton pages for the rest.
author | Ludovic Chabant <ludovic@chabant.com> |
---|---|
date | Sat, 25 Jul 2015 00:47:27 -0700 |
parents | |
children | dce482f7c62d |
rev | line source |
---|---|
504
20fcadaaf871
docs: Add some API documentation.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff
changeset
|
1 --- |
20fcadaaf871
docs: Add some API documentation.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff
changeset
|
2 title: Chef Commands |
20fcadaaf871
docs: Add some API documentation.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff
changeset
|
3 needs_pygments: true |
20fcadaaf871
docs: Add some API documentation.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff
changeset
|
4 --- |
20fcadaaf871
docs: Add some API documentation.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff
changeset
|
5 |
20fcadaaf871
docs: Add some API documentation.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff
changeset
|
6 To provide new `chef` commands, you need to override the `getCommands` method of |
20fcadaaf871
docs: Add some API documentation.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff
changeset
|
7 your plugin, and return command instances: |
20fcadaaf871
docs: Add some API documentation.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff
changeset
|
8 |
20fcadaaf871
docs: Add some API documentation.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff
changeset
|
9 |
20fcadaaf871
docs: Add some API documentation.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff
changeset
|
10 {% highlight 'python' %} |
20fcadaaf871
docs: Add some API documentation.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff
changeset
|
11 class MyPlugin(PieCrustPlugin): |
20fcadaaf871
docs: Add some API documentation.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff
changeset
|
12 name = 'myplugin' |
20fcadaaf871
docs: Add some API documentation.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff
changeset
|
13 |
20fcadaaf871
docs: Add some API documentation.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff
changeset
|
14 def getCommands(self): |
20fcadaaf871
docs: Add some API documentation.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff
changeset
|
15 return [ |
20fcadaaf871
docs: Add some API documentation.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff
changeset
|
16 MyNewCommand()] |
20fcadaaf871
docs: Add some API documentation.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff
changeset
|
17 {% endhighlight %} |
20fcadaaf871
docs: Add some API documentation.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff
changeset
|
18 |
20fcadaaf871
docs: Add some API documentation.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff
changeset
|
19 |
20fcadaaf871
docs: Add some API documentation.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff
changeset
|
20 To create a command class, inherit from the `ChefCommand` base class: |
20fcadaaf871
docs: Add some API documentation.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff
changeset
|
21 |
20fcadaaf871
docs: Add some API documentation.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff
changeset
|
22 {% highlight 'python' %} |
20fcadaaf871
docs: Add some API documentation.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff
changeset
|
23 from piecrust.commands.base import ChefCommand |
20fcadaaf871
docs: Add some API documentation.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff
changeset
|
24 |
20fcadaaf871
docs: Add some API documentation.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff
changeset
|
25 |
20fcadaaf871
docs: Add some API documentation.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff
changeset
|
26 class MyNewCommand(ChefCommand): |
20fcadaaf871
docs: Add some API documentation.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff
changeset
|
27 def __init__(self): |
20fcadaaf871
docs: Add some API documentation.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff
changeset
|
28 super(MyNewCommand, self).__init__() |
20fcadaaf871
docs: Add some API documentation.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff
changeset
|
29 self.name = 'foobar' |
20fcadaaf871
docs: Add some API documentation.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff
changeset
|
30 self.description = "Does some foobar thing." |
20fcadaaf871
docs: Add some API documentation.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff
changeset
|
31 |
20fcadaaf871
docs: Add some API documentation.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff
changeset
|
32 def setupParser(self, parser, app): |
20fcadaaf871
docs: Add some API documentation.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff
changeset
|
33 parser.add_argument('thing') |
20fcadaaf871
docs: Add some API documentation.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff
changeset
|
34 |
20fcadaaf871
docs: Add some API documentation.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff
changeset
|
35 def run(self, ctx): |
20fcadaaf871
docs: Add some API documentation.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff
changeset
|
36 print("Doing %s" % ctx.args.thing) |
20fcadaaf871
docs: Add some API documentation.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff
changeset
|
37 {% endhighlight %} |
20fcadaaf871
docs: Add some API documentation.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff
changeset
|
38 |
20fcadaaf871
docs: Add some API documentation.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff
changeset
|
39 |
20fcadaaf871
docs: Add some API documentation.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff
changeset
|
40 * The `name` will be used for command line invocation, _i.e._ your new command |
20fcadaaf871
docs: Add some API documentation.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff
changeset
|
41 will be invoked with `chef foobar`. |
20fcadaaf871
docs: Add some API documentation.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff
changeset
|
42 * The `description` will be used for help pages like `chef --help`. |
20fcadaaf871
docs: Add some API documentation.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff
changeset
|
43 * The `setupParser` method passes an `argparse.ArgumentParser` and a `PieCrust` |
20fcadaaf871
docs: Add some API documentation.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff
changeset
|
44 application. You're supposed to setup the syntax for your commend there. |
20fcadaaf871
docs: Add some API documentation.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff
changeset
|
45 * The `run` method is called when your command is executed. The `ctx` object |
20fcadaaf871
docs: Add some API documentation.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff
changeset
|
46 contains a couple useful things, among others: |
20fcadaaf871
docs: Add some API documentation.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff
changeset
|
47 * `args` is the namespace obtained from running `parse_args`. It has all the |
20fcadaaf871
docs: Add some API documentation.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff
changeset
|
48 values of the arguments for your command. |
20fcadaaf871
docs: Add some API documentation.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff
changeset
|
49 * `app` is the instance of the current `PieCrust` application. |
20fcadaaf871
docs: Add some API documentation.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff
changeset
|
50 * For the other things, check-out `piecrust.commands.base.CommandContext`. |
20fcadaaf871
docs: Add some API documentation.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff
changeset
|
51 |