From 469f10e4a7d3cfdd6cc937344dc47b89608198fa Mon Sep 17 00:00:00 2001 From: Will Kahn-Greene Date: Wed, 23 May 2012 21:16:18 -0400 Subject: [PATCH] Add plugin writer's quickstart guide --- docs/source/index.rst | 1 + docs/source/pluginwriter/quickstart.rst | 189 ++++++++++++++++++++++++ 2 files changed, 190 insertions(+) create mode 100644 docs/source/pluginwriter/quickstart.rst diff --git a/docs/source/index.rst b/docs/source/index.rst index 3b13b1bc..5b8d5c85 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -47,6 +47,7 @@ This guide covers writing new GNU MediaGoblin plugins. :maxdepth: 1 pluginwriter/foreward + pluginwriter/quickstart Indices and tables 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 + . + + +=========== +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 +``_ + + +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 ``_ +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 +`_ for more information on +packaging your plugin. -- 2.25.1