Add plugin writer's quickstart guide

1 files changed, 189 insertions, 0 deletions

diff --git a/docs/source/pluginwriter/quickstart.rst b/docs/source/pluginwriter/quickstart.rst
new file mode 100644
index 00000000..73531381
--- /dev/null
+++ b/docs/source/pluginwriter/quickstart.rst
@@ -0,0 +1,189 @@
+.. MediaGoblin Documentation
+
+   Written in 2011, 2012 by MediaGoblin contributors
+
+   To the extent possible under law, the author(s) have dedicated all
+   copyright and related and neighboring rights to this software to
+   the public domain worldwide. This software is distributed without
+   any warranty.
+
+   You should have received a copy of the CC0 Public Domain
+   Dedication along with this software. If not, see
+   <http://creativecommons.org/publicdomain/zero/1.0/>.
+
+
+===========
+Quick Start
+===========
+
+This is a quick start. It's not comprehensive, but it walks through
+writing a basic plugin called "sampleplugin" which logs "I've been
+started!" when ``setup_plugin()`` has been called.
+
+.. todo: Rewrite this to be a useful plugin
+
+
+Step 1: Files and directories
+=============================
+
+GNU MediaGoblin plugins are Python projects at heart. As such, you should
+use a standard Python project directory tree::
+
+    sampleplugin/
+     |- README
+     |- LICENSE
+     |- setup.py
+     |- sampleplugin/
+        |- __init__.py
+
+
+The outer ``sampleplugin`` directory holds all the project files.
+
+The ``README`` should cover what your plugin does, how to install it,
+how to configure it, and all the sorts of things a README should
+cover.
+
+The ``LICENSE`` should have the license under which you're
+distributing your plugin.
+
+The inner ``sampleplugin`` directory is the Python package that holds
+your plugin's code.
+
+The ``__init__.py`` denotes that this is a Python package. It also
+holds the plugin code.
+
+
+Step 2: README
+==============
+
+Here's a rough ``README``. Generally, you want more information
+because this is the file that most people open when they want to learn
+more about your project.
+
+::
+
+    README
+    ======
+
+    This is a sample plugin. It logs a line when ``setup__plugin()`` is
+    run.
+
+
+Step 3: LICENSE
+===============
+
+GNU MediaGoblin plugins must be licensed under the AGPLv3 or later. So
+the LICENSE file should be the AGPLv3 text which you can find at
+`<http://www.gnu.org/licenses/agpl-3.0.html>`_
+
+
+Step 4: setup.py
+================
+
+This file is used for packaging and distributing your plugin.
+
+We'll use a basic one::
+
+    from setuptools import setup, find_packages
+
+    setup(
+        name='sampleplugin',
+        version='1.0',
+        packages=find_packages(),
+        include_package_data=True,
+        install_requires=[],
+        license='AGPLv3',
+        )
+
+
+See `<http://docs.python.org/distutils/index.html#distutils-index>`_
+for more details.
+
+
+Step 5: the code
+================
+
+The code for ``__init__.py`` looks like this:
+
+.. code-block:: python
+   :linenos:
+   :emphasize-lines: 8,19
+
+    import logging
+    from mediagoblin.tools.pluginapi import Plugin, get_config
+
+
+    _log = logging.getLogger(__name__)
+
+
+    class SamplePlugin(Plugin):
+        """
+        This is a sample plugin class. It automatically registers itself
+        with MediaGoblin when this module is imported.
+
+        The setup_plugin method prints configuration for this plugin if
+        there is any.
+        """
+        def __init__(self):
+            pass
+
+        def setup_plugin(self):
+            _log.info("I've been started!")
+            config = get_config('sampleplugin')
+            if config:
+                _log.info('%r' % config)
+            else:
+                _log.info('There is no configuration set.')
+
+
+Line 8 defines a class called ``SamplePlugin`` that subclasses
+``Plugin`` from ``mediagoblin.tools.pluginapi``. When the class is
+defined, it gets registered with MediaGoblin and MediaGoblin will then
+call ``setup_plugin`` on it.
+
+Line 19 defines ``setup_plugin``. This gets called when MediaGoblin
+starts up after it's registered all the plugins. This is where you can
+do any initialization for your plugin.
+
+
+Step 6: Installation and configuration
+======================================
+
+To install the plugin for development, you need to make sure it's
+available to the Python interpreter that's running MediaGoblin.
+
+There are a couple of ways to do this, but we're going to pick the
+easy one.
+
+Use ``python`` from your MediaGoblin virtual environment and do::
+
+    python setup.py develop
+
+Any changes you make to your plugin will be available in your
+MediaGoblin virtual environment.
+
+Then adjust your ``mediagoblin.ini`` file to load the plugin::
+
+    [plugins]
+
+    [[sampleplugin]]
+
+
+Step 7: That's it!
+==================
+
+When you launch MediaGoblin, it'll load the plugin and you'll see
+evidence of that in the log file.
+
+That's it for the quick start!
+
+
+Where to go from here
+=====================
+
+See the documentation on the plugin API for code samples and other
+things you can use when building your plugin.
+
+See `Hitchhiker's Guide to Packaging
+<http://guide.python-distribute.org/>`_ for more information on
+packaging your plugin.