Merge pull request #989 from getpelican/plugins-recipes

Start a section about plugin recipes in the docs

docs/plugins.rst

@@ -123,3 +123,69 @@ request if you need them!
    static_generate_context     static_generator_context
    static_generate_preread     static_generator_preread
    ==========================  ===========================
+
+Recipes
+=======
+
+We eventually realised some of the recipes to create plugins would be best
+shared in the documentation somewhere, so here they are!
+
+How to create a new reader
+--------------------------
+
+One thing you might want is to add the support for your very own input
+format. While it might make sense to add this feature in pelican core, we
+wisely chose to avoid this situation, and have the different readers defined in
+plugins.
+
+The rationale behind this choice is mainly that plugins are really easy to
+write and don't slow down pelican itself when they're not active.
+
+No more talking, here is the example::
+
+    from pelican import signals
+    from pelican.readers import EXTENSIONS, Reader
+
+    # Create a new reader class, inheriting from the pelican.reader.Reader
+    class NewReader(Reader):
+        enabled = True  # Yeah, you probably want that :-)
+
+        # The list of extensions you want this reader to match with.
+        # In the case multiple readers use the same extensions, the latest will
+        # win (so the one you're defining here, most probably).
+        file_extensions = ['yeah']
+
+        # You need to have a read method, which takes a filename and returns
+        # some content and the associated metadata.
+        def read(self, filename):
+            metadata = {'title': 'Oh yeah',
+                        'category': 'Foo',
+                        'date': '2012-12-01'}
+
+            parsed = {}
+            for key, value in metadata.items():
+                parsed[key] = self.process_metadata(key, value)
+
+            return "Some content", parsed
+
+    def add_reader(arg):
+        EXTENSIONS['yeah'] = NewReader
+
+    # this is how pelican works.
+    def register():
+        signals.initialized.connect(add_reader)
+
+
+Adding a new generator
+----------------------
+
+Adding a new generator is also really easy. You might want to have a look at
+:doc:`internals` for more information on how to create your own generator.
+
+::
+
+    def get_generators(generators):
+        # define a new generator here if you need to
+        return generators
+
+    signals.get_generators.connect(get_generators)