docs/source/pluginwriter/quickstart.rst

   1 .. MediaGoblin Documentation
   2
   3    Written in 2011, 2012 by MediaGoblin contributors
   4
   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
   8    any warranty.
   9
  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/>.
  13
  14
  15 ===========
  16 Quick Start
  17 ===========
  18
  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.
  22
  23 .. todo: Rewrite this to be a useful plugin
  24
  25
  26 Step 1: Files and directories
  27 =============================
  28
  29 GNU MediaGoblin plugins are Python projects at heart. As such, you should
  30 use a standard Python project directory tree::
  31
  32     sampleplugin/
  33      |- README
  34      |- LICENSE
  35      |- setup.py
  36      |- sampleplugin/
  37         |- __init__.py
  38
  39
  40 The outer ``sampleplugin`` directory holds all the project files.
  41
  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
  44 cover.
  45
  46 The ``LICENSE`` should have the license under which you're
  47 distributing your plugin.
  48
  49 The inner ``sampleplugin`` directory is the Python package that holds
  50 your plugin's code.
  51
  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.
  55
  56
  57 Step 2: README
  58 ==============
  59
  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.
  63
  64 ::
  65
  66     README
  67     ======
  68
  69     This is a sample plugin. It logs a line when ``setup__plugin()`` is
  70     run.
  71
  72
  73 Step 3: LICENSE
  74 ===============
  75
  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>`_
  79
  80
  81 Step 4: setup.py
  82 ================
  83
  84 This file is used for packaging and distributing your plugin.
  85
  86 We'll use a basic one::
  87
  88     from setuptools import setup, find_packages
  89
  90     setup(
  91         name='sampleplugin',
  92         version='1.0',
  93         packages=find_packages(),
  94         include_package_data=True,
  95         install_requires=[],
  96         license='AGPLv3',
  97         )
  98
  99
 100 See `<http://docs.python.org/distutils/index.html#distutils-index>`_
 101 for more details.
 102
 103
 104 Step 5: the code
 105 ================
 106
 107 The code for ``__init__.py`` looks like this:
 108
 109 .. code-block:: python
 110    :linenos:
 111    :emphasize-lines: 12,23
 112
 113     import logging
 114     from mediagoblin.tools.pluginapi import Plugin, get_config
 115
 116
 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__)
 120
 121
 122     # This is the function that gets called when the setup
 123     # hook fires.
 124     def setup_plugin():
 125         _log.info("I've been started!")
 126         config = get_config('sampleplugin')
 127         if config:
 128             _log.info('%r' % config)
 129         else:
 130             _log.info('There is no configuration set.')
 131
 132
 133     # This is a dict that specifies which hooks this plugin uses.
 134     # This one only uses one hook: setup.
 135     hooks = {
 136         'setup': setup_plugin
 137         }
 138
 139
 140 Line 12 defines the ``setup_plugin`` function.
 141
 142 Line 23 defines ``hooks``. When MediaGoblin loads this file, it sees
 143 ``hooks`` and registers all the callables with their respective hooks.
 144
 145
 146 Step 6: Installation and configuration
 147 ======================================
 148
 149 To install the plugin for development, you need to make sure it's
 150 available to the Python interpreter that's running MediaGoblin.
 151
 152 There are a couple of ways to do this, but we're going to pick the
 153 easy one.
 154
 155 Use ``python`` from your MediaGoblin virtual environment and do::
 156
 157     python setup.py develop
 158
 159 Any changes you make to your plugin will be available in your
 160 MediaGoblin virtual environment.
 161
 162 Then adjust your ``mediagoblin.ini`` file to load the plugin::
 163
 164     [plugins]
 165
 166     [[sampleplugin]]
 167
 168
 169 Step 7: That's it!
 170 ==================
 171
 172 When you launch MediaGoblin, it'll load the plugin and you'll see
 173 evidence of that in the log file.
 174
 175 That's it for the quick start!
 176
 177
 178 Where to go from here
 179 =====================
 180
 181 See the documentation on the :ref:`plugin-api-chapter` for code
 182 samples and other things you can use when building your plugin.  If
 183 your plugin needs its own database models, see
 184 :ref:`plugin-database-chapter`.
 185
 186 See `Hitchhiker's Guide to Packaging
 187 <http://guide.python-distribute.org/>`_ for more information on
 188 packaging your plugin.