1 .. MediaGoblin Documentation
3 Written in 2011, 2012 by MediaGoblin contributors
5 To the extent possible under law, the author(s) have dedicated all
6 copyright and related and neighboring rights to this software to
7 the public domain worldwide. This software is distributed without
10 You should have received a copy of the CC0 Public Domain
11 Dedication along with this software. If not, see
12 <http://creativecommons.org/publicdomain/zero/1.0/>.
19 This is a quick start. It's not comprehensive, but it walks through
20 writing a basic plugin called "sampleplugin" which logs "I've been
21 started!" when ``setup_plugin()`` has been called.
23 .. todo: Rewrite this to be a useful plugin
26 Step 1: Files and directories
27 =============================
29 GNU MediaGoblin plugins are Python projects at heart. As such, you should
30 use a standard Python project directory tree::
40 The outer ``sampleplugin`` directory holds all the project files.
42 The ``README`` should cover what your plugin does, how to install it,
43 how to configure it, and all the sorts of things a README should
46 The ``LICENSE`` should have the license under which you're
47 distributing your plugin.
49 The inner ``sampleplugin`` directory is the Python package that holds
52 The ``__init__.py`` denotes that this is a Python package. It also
53 holds the plugin code and the ``hooks`` dict that specifies which
54 hooks the sampleplugin uses.
60 Here's a rough ``README``. Generally, you want more information
61 because this is the file that most people open when they want to learn
62 more about your project.
69 This is a sample plugin. It logs a line when ``setup__plugin()`` is
76 GNU MediaGoblin plugins must be licensed under the AGPLv3 or later. So
77 the LICENSE file should be the AGPLv3 text which you can find at
78 `<http://www.gnu.org/licenses/agpl-3.0.html>`_
84 This file is used for packaging and distributing your plugin.
86 We'll use a basic one::
88 from setuptools import setup, find_packages
93 packages=find_packages(),
94 include_package_data=True,
100 See `<http://docs.python.org/distutils/index.html#distutils-index>`_
107 The code for ``__init__.py`` looks like this:
109 .. code-block:: python
111 :emphasize-lines: 12,23
114 from mediagoblin.tools.pluginapi import Plugin, get_config
117 # This creates a logger that you can use to log information to
118 # the console or a log file.
119 _log = logging.getLogger(__name__)
122 # This is the function that gets called when the setup
125 _log.info("I've been started!")
126 config = get_config('sampleplugin')
128 _log.info('%r' % config)
130 _log.info('There is no configuration set.')
133 # This is a dict that specifies which hooks this plugin uses.
134 # This one only uses one hook: setup.
136 'setup': setup_plugin
140 Line 12 defines the ``setup_plugin`` function.
142 Line 23 defines ``hooks``. When MediaGoblin loads this file, it sees
143 ``hooks`` and registers all the callables with their respective hooks.
146 Step 6: Installation and configuration
147 ======================================
149 To install the plugin for development, you need to make sure it's
150 available to the Python interpreter that's running MediaGoblin.
152 There are a couple of ways to do this, but we're going to pick the
155 Use ``python`` from your MediaGoblin virtual environment and do::
157 python setup.py develop
159 Any changes you make to your plugin will be available in your
160 MediaGoblin virtual environment.
162 Then adjust your ``mediagoblin.ini`` file to load the plugin::
172 When you launch MediaGoblin, it'll load the plugin and you'll see
173 evidence of that in the log file.
175 That's it for the quick start!
178 Where to go from here
179 =====================
181 See the documentation on the plugin API for code samples and other
182 things you can use when building your plugin.
184 See `Hitchhiker's Guide to Packaging
185 <http://guide.python-distribute.org/>`_ for more information on
186 packaging your plugin.