# HG changeset patch
# User Ludovic Chabant <ludovic@chabant.com>
# Date 1437810447 25200
# Node ID 20fcadaaf8712d698ae278945195ade08ef06117
# Parent  61d53d2163d6dcea8b57fc5b2175306d1b3fcaeb
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.

diff -r 61d53d2163d6 -r 20fcadaaf871 docs/api/02_components.md
--- /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')}}
+
diff -r 61d53d2163d6 -r 20fcadaaf871 docs/api/02_components/01_commands.md
--- /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`.
+
diff -r 61d53d2163d6 -r 20fcadaaf871 docs/api/02_components/02_sources.md
--- /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`
+
diff -r 61d53d2163d6 -r 20fcadaaf871 docs/api/02_components/03_data-providers.md
--- /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`
+
diff -r 61d53d2163d6 -r 20fcadaaf871 docs/api/02_components/04_template-engines.md
--- /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`
+
+
diff -r 61d53d2163d6 -r 20fcadaaf871 docs/api/02_components/05_formatters.md
--- /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`
+
diff -r 61d53d2163d6 -r 20fcadaaf871 docs/api/02_components/06_processors.md
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/docs/api/02_components/06_processors.md	Sat Jul 25 00:47:27 2015 -0700
@@ -0,0 +1,6 @@
+---
+title: Processors
+---
+
+`TODO`
+
diff -r 61d53d2163d6 -r 20fcadaaf871 docs/api/02_components/07_importers.md
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/docs/api/02_components/07_importers.md	Sat Jul 25 00:47:27 2015 -0700
@@ -0,0 +1,6 @@
+---
+title: Importers
+---
+
+`TODO`
+