# HG changeset patch # User Ludovic Chabant # Date 1437719711 25200 # Node ID 61d53d2163d6dcea8b57fc5b2175306d1b3fcaeb # Parent f07b7562328f04becfdd1922db768f3196456574 docs: Start a proper "code/API" section. diff -r f07b7562328f -r 61d53d2163d6 docs/api/00__index.md --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/api/00__index.md Thu Jul 23 23:35:11 2015 -0700 @@ -0,0 +1,17 @@ +--- +title: Code +--- + +PieCrust can be extended with plugins in order to support additional features +such as new [formatters][1], [processors][2], or [template engines][3] (among +other things). + +[Creating a plugin][4] is very easy in itself, but requires making a +`setuptools` package in order to be easily shared with other people. + + +[1]: {{docurl('content/formatters')}} +[2]: {{docurl('asset-pipeline')}} +[3]: {{docurl('content/templating')}} +[4]: {{apiurl('plugins')}} + diff -r f07b7562328f -r 61d53d2163d6 docs/api/01_plugins.md --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/api/01_plugins.md Thu Jul 23 23:35:11 2015 -0700 @@ -0,0 +1,77 @@ +--- +title: Plugins +--- + +To create a PieCrust plugin, you need to do a few things: + +* Create a correct `setuptools` package. +* Implement a sub-class of `PieCrustPlugin`. +* Write a couple lines of boilerplate code. + + +## Packaging plugins + +PieCrust plugins are expected to be available on [Pypi][] for better integration +with `chef` commands. For instance, the `chef plugins list -a` will list all +PieCrust plugins from Pypi. + +A PieCrust plugin package must: + +* Be named `PieCrust-FooBar`, where `FooBar` is the name of the plugin. +* Have a module named `piecrust_foobar`, which is basically the lower-case + version of the package name, with an underscore instead of a dash. + +You can refer to the [`setuptools` documentation][st] for more information. + + +## The plugin class + +A PieCrust plugin is an instance of a class that derives from `PieCrustPlugin`. +The only required thing you need to override is the name of the plugin: + + from piecrust.plugins.base import PieCrustPlugin + + class FooBarPlugin(PieCrustPlugin): + name = 'FooBar' + +The plugin class has a whole bunch of functions returning whatever your plugin +may want to extend: formatters, template engines, `chef` commands, sources, etc. +Each one of those returns an array of instances or classes, depending on the +situation. + +Check the `piecrust.plugins.builtin.BuiltInPlugin` to see how all PieCrust +functionality is implemented. + + +## Boilerplate code + +Now we have a plugin class, and a Pypi package that PieCrust can find if needed. +All we need is a way to tell PieCrust how to find your plugin class in that +package. + +In the required `piecrust_foobar` module, you need to define a +`__piecrust_plugin__` global variable that points to your plugin class: + + __piecrust_plugin__ = FooBarPlugin + +That's what PieCrust will use to instantiate your plugin. + + +## Loading the plugin + +Now you can add your plugin to a PieCrust website by adding this to the website +configuration: + + site: + plugins: foobar + +PieCrust will prepend `piecrust_` to each specified plugin name and attempt to +load that as a module (`import piecrust_foobar`). If this succeeds, it will look +for a `__piecrust_plugin__` in that module, and expect its value to be a class +that inherits from `PieCrustPlugin`. If everything's OK, it will instantiate +that class and query it for various services and components when necessary. + + +[pypi]: https://pypi.python.org/pypi +[st]: http://pythonhosted.org/setuptools/ + diff -r f07b7562328f -r 61d53d2163d6 docs/config.yml --- a/docs/config.yml Thu Jul 23 23:34:36 2015 -0700 +++ b/docs/config.yml Thu Jul 23 23:35:11 2015 -0700 @@ -10,11 +10,19 @@ type: ordered data_endpoint: site.docs default_layout: doc + api: + type: ordered + data_endpoint: site.api + default_layout: api routes: - url: /docs/%path:slug% source: docs func: docurl(slug) + - + url: /api/%path:slug% + source: api + func: apiurl(slug) baker: assets_dirs: diff -r f07b7562328f -r 61d53d2163d6 docs/pages/code.md --- a/docs/pages/code.md Thu Jul 23 23:34:36 2015 -0700 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,80 +0,0 @@ ---- -title: Code -header_class: code ---- - -## PieCrust plugins - -To create a PieCrust plugin, you need to do a few things: - -* Create a correct `setuptools` package. -* Implement a sub-class of `PieCrustPlugin`. -* Write a couple lines of boilerplate code. - - -### Packaging plugins - -PieCrust plugins are expected to be available on [Pypi][] for better integration -with `chef` commands. For instance, the `chef plugins list -a` will list all -PieCrust plugins from Pypi. - -A PieCrust plugin package must: - -* Be named `PieCrust-FooBar`, where `FooBar` is the name of the plugin. -* Have a module named `piecrust_foobar`, which is basically the lower-case - version of the package name, with an underscore instead of a dash. - -You can refer to the [`setuptools` documentation][st] for more information. - - -### The plugin class - -A PieCrust plugin is an instance of a class that derives from `PieCrustPlugin`. -The only required thing you need to override is the name of the plugin: - - from piecrust.plugins.base import PieCrustPlugin - - class FooBarPlugin(PieCrustPlugin): - name = 'FooBar' - -The plugin class has a whole bunch of functions returning whatever your plugin -may want to extend: formatters, template engines, `chef` commands, sources, etc. -Each one of those returns an array of instances or classes, depending on the -situation. - -Check the `piecrust.plugins.builtin.BuiltInPlugin` to see how all PieCrust -functionality is implemented. - - -### Boilerplate code - -Now we have a plugin class, and a Pypi package that PieCrust can find if needed. -All we need is a way to tell PieCrust how to find your plugin class in that -package. - -In the required `piecrust_foobar` module, you need to define a -`__piecrust_plugin__` global variable that points to your plugin class: - - __piecrust_plugin__ = FooBarPlugin - -That's what PieCrust will use to instantiate your plugin. - - -### Loading the plugin - -Now you can add your plugin to a PieCrust website by adding this to the website -configuration: - - site: - plugins: foobar - -PieCrust will prepend `piecrust_` to each specified plugin name and attempt to -load that as a module (`import piecrust_foobar`). If this succeeds, it will look -for a `__piecrust_plugin__` in that module, and expect its value to be a class -that inherits from `PieCrustPlugin`. If everything's OK, it will instantiate -that class and query it for various services and components when necessary. - - -[pypi]: https://pypi.python.org/pypi -[st]: http://pythonhosted.org/setuptools/ - diff -r f07b7562328f -r 61d53d2163d6 docs/templates/api.html --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/templates/api.html Thu Jul 23 23:35:11 2015 -0700 @@ -0,0 +1,8 @@ +{% extends "section-page.html" %} + +{% block header %} +
+

{{ page.title }}

+
+{% endblock %} + diff -r f07b7562328f -r 61d53d2163d6 docs/templates/default.html --- a/docs/templates/default.html Thu Jul 23 23:34:36 2015 -0700 +++ b/docs/templates/default.html Thu Jul 23 23:35:11 2015 -0700 @@ -30,12 +30,7 @@ PieCrust diff -r f07b7562328f -r 61d53d2163d6 docs/templates/doc.html --- a/docs/templates/doc.html Thu Jul 23 23:34:36 2015 -0700 +++ b/docs/templates/doc.html Thu Jul 23 23:35:11 2015 -0700 @@ -1,16 +1,4 @@ -{% extends "default.html" %} - -{% macro pagelink(title, url) -%} - {{title}} -{%- endmacro %} - -{% block head %} -{% if page.needs_pygments %} - -{% endif %} -{% endblock %} +{% extends "section-page.html" %} {% block header %}
@@ -18,28 +6,3 @@
{% endblock %} -{% block content %} -
-
- {{ content|safe }} -
- -
-{% endblock %} - diff -r f07b7562328f -r 61d53d2163d6 docs/templates/inc/family-sidebar.html --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/templates/inc/family-sidebar.html Thu Jul 23 23:35:11 2015 -0700 @@ -0,0 +1,20 @@ +{% macro pagelink(title, url) -%} + {{title}} +{%- endmacro %} + + + diff -r f07b7562328f -r 61d53d2163d6 docs/templates/inc/main-navigation.html --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/templates/inc/main-navigation.html Thu Jul 23 23:35:11 2015 -0700 @@ -0,0 +1,6 @@ + diff -r f07b7562328f -r 61d53d2163d6 docs/templates/section-page.html --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/templates/section-page.html Thu Jul 23 23:35:11 2015 -0700 @@ -0,0 +1,22 @@ +{% extends "default.html" %} + +{% block head %} +{% if page.needs_pygments %} + +{% endif %} +{% endblock %} + +{% block content %} +
+
+ {{ content|safe }} +
+ +
+{% endblock %} + +