190 lines
4.7 KiB
ReStructuredText
190 lines
4.7 KiB
ReStructuredText
.. 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.
|