Mercurial > piecrust2
changeset 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 | 61d53d2163d6 |
| children | 883a5544cd7f |
| files | docs/api/02_components.md docs/api/02_components/01_commands.md docs/api/02_components/02_sources.md docs/api/02_components/03_data-providers.md docs/api/02_components/04_template-engines.md docs/api/02_components/05_formatters.md docs/api/02_components/06_processors.md docs/api/02_components/07_importers.md |
| diffstat | 8 files changed, 100 insertions(+), 0 deletions(-) [+] |
line wrap: on
line diff
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/api/02_components.md Sat Jul 25 00:47:27 2015 -0700 @@ -0,0 +1,12 @@ +--- +title: Plugin Components +--- + +Once you've [created a plugin][1], you need to make it provide new _components_. + +{% for comp in family.children -%} +* [{{comp.title}}]({{comp.url}}) +{% endfor %} + +[1]: {{apiurl('plugins')}} +
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/api/02_components/01_commands.md Sat Jul 25 00:47:27 2015 -0700 @@ -0,0 +1,51 @@ +--- +title: Chef Commands +needs_pygments: true +--- + +To provide new `chef` commands, you need to override the `getCommands` method of +your plugin, and return command instances: + + +{% highlight 'python' %} +class MyPlugin(PieCrustPlugin): + name = 'myplugin' + + def getCommands(self): + return [ + MyNewCommand()] +{% endhighlight %} + + +To create a command class, inherit from the `ChefCommand` base class: + +{% highlight 'python' %} +from piecrust.commands.base import ChefCommand + + +class MyNewCommand(ChefCommand): + def __init__(self): + super(MyNewCommand, self).__init__() + self.name = 'foobar' + self.description = "Does some foobar thing." + + def setupParser(self, parser, app): + parser.add_argument('thing') + + def run(self, ctx): + print("Doing %s" % ctx.args.thing) +{% endhighlight %} + + +* The `name` will be used for command line invocation, _i.e._ your new command + will be invoked with `chef foobar`. +* The `description` will be used for help pages like `chef --help`. +* The `setupParser` method passes an `argparse.ArgumentParser` and a `PieCrust` + application. You're supposed to setup the syntax for your commend there. +* The `run` method is called when your command is executed. The `ctx` object + contains a couple useful things, among others: + * `args` is the namespace obtained from running `parse_args`. It has all the + values of the arguments for your command. + * `app` is the instance of the current `PieCrust` application. + * For the other things, check-out `piecrust.commands.base.CommandContext`. +
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/api/02_components/02_sources.md Sat Jul 25 00:47:27 2015 -0700 @@ -0,0 +1,6 @@ +--- +title: Page Sources +--- + +`TODO` +
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/api/02_components/03_data-providers.md Sat Jul 25 00:47:27 2015 -0700 @@ -0,0 +1,6 @@ +--- +title: Data Providers +--- + +`TODO` +
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/api/02_components/04_template-engines.md Sat Jul 25 00:47:27 2015 -0700 @@ -0,0 +1,7 @@ +--- +title: Template Engines +--- + +`TODO` + +
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/api/02_components/05_formatters.md Sat Jul 25 00:47:27 2015 -0700 @@ -0,0 +1,6 @@ +--- +title: Formatters +--- + +`TODO` +