Mercurial > piecrust2

changeset 503:61d53d2163d6

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
docs: Start a proper "code/API" section.
author Ludovic Chabant <ludovic@chabant.com>
date Thu, 23 Jul 2015 23:35:11 -0700
parents f07b7562328f
children 20fcadaaf871
files docs/api/00__index.md docs/api/01_plugins.md docs/config.yml docs/pages/code.md docs/templates/api.html docs/templates/default.html docs/templates/doc.html docs/templates/inc/family-sidebar.html docs/templates/inc/main-navigation.html docs/templates/section-page.html
diffstat 10 files changed, 160 insertions(+), 124 deletions(-) [+]
line wrap: on
line diff
--- /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')}}
+
--- /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/
+
--- 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:
--- 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/
-
--- /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 %}
+<header class="code">
+    <h1>{{ page.title }}</h1>
+</header>
+{% endblock %}
+
--- 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 @@
                     <a class="navbar-brand" href="{{site.root}}">PieCrust</a>
                 </div>
                 <div class="collapse navbar-collapse" id="piecrust-menu">
-                    <ul class="nav navbar-nav navbar-right">
-                        <li><a href="{{ pcurl('getting-started') }}">Getting Started</a></li>
-                        <li><a href="{{ pcurl('docs') }}">Documentation</a></li>
-                        <li><a href="{{ pcurl('code') }}">Code</a></li>
-                        <li><a href="{{ pcurl('support') }}">Support</a></li>
-                    </ul>
+                    {% include 'inc/main-navigation.html' %}
                 </div>
             </div>
         </nav>
--- 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) -%}
-    <a href="{{url}}"{% if url == page.url %} class="active"{% endif %}>{{title}}</a>
-{%- endmacro %}
-
-{% block head %}
-{% if page.needs_pygments %}
-    <style type="text/css">
-    {{highlight_css()}}
-    </style>
-{% endif %}
-{% endblock %}
+{% extends "section-page.html" %}
 
 {% block header %}
 <header class="documentation">
@@ -18,28 +6,3 @@
 </header>
 {% endblock %}
 
-{% block content %}
-<div class="container">
-    <section class="col-md-8">
-    {{ content|safe }}
-    </section>
-    <aside class="col-md-4">
-        <ul class="doc-level1">
-        {% for p in family.root %}
-        {% if p.is_dir and p.is_page %}
-            <li>{{ pagelink(p.title, p.url) }}
-                <ul class="doc-level2">
-                {% for p2 in p.children %}
-                    <li>{{ pagelink(p2.title, p2.url) }}</li>
-                {% endfor %}
-                </ul>
-            </li>
-        {% elif not p.is_dir and p.order %}
-            <li>{{ pagelink(p.title, p.url) }}</li>
-        {% endif %}
-        {% endfor %}
-        </ul>
-    </aside>
-</div>
-{% endblock %}
-
--- /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) -%}
+    <a href="{{url}}"{% if url == page.url %} class="active"{% endif %}>{{title}}</a>
+{%- endmacro %}
+
+<ul class="doc-level1">
+{% for p in family.root %}
+{% if p.is_dir and p.is_page %}
+    <li>{{ pagelink(p.title, p.url) }}
+        <ul class="doc-level2">
+        {% for p2 in p.children %}
+            <li>{{ pagelink(p2.title, p2.url) }}</li>
+        {% endfor %}
+        </ul>
+    </li>
+{% elif not p.is_dir and p.order %}
+    <li>{{ pagelink(p.title, p.url) }}</li>
+{% endif %}
+{% endfor %}
+</ul>
+
--- /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 @@
+<ul class="nav navbar-nav navbar-right">
+    <li><a href="{{ pcurl('getting-started') }}">Getting Started</a></li>
+    <li><a href="{{ pcurl('docs') }}">Documentation</a></li>
+    <li><a href="{{ pcurl('api') }}">Code</a></li>
+    <li><a href="{{ pcurl('support') }}">Support</a></li>
+</ul>
--- /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 %}
+    <style type="text/css">
+    {{highlight_css()}}
+    </style>
+{% endif %}
+{% endblock %}
+
+{% block content %}
+<div class="container">
+    <section class="col-md-8">
+    {{ content|safe }}
+    </section>
+    <aside class="col-md-4">
+        {% include 'inc/family-sidebar.html' %}
+    </aside>
+</div>
+{% endblock %}
+
+