Commit | Line | Data |
---|---|---|
469f10e4 WKG |
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 | |
05e007c1 WKG |
53 | holds the plugin code and the ``hooks`` dict that specifies which |
54 | hooks the sampleplugin uses. | |
469f10e4 WKG |
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: | |
05e007c1 | 111 | :emphasize-lines: 12,23 |
469f10e4 WKG |
112 | |
113 | import logging | |
114 | from mediagoblin.tools.pluginapi import Plugin, get_config | |
115 | ||
116 | ||
05e007c1 WKG |
117 | # This creates a logger that you can use to log information to |
118 | # the console or a log file. | |
469f10e4 WKG |
119 | _log = logging.getLogger(__name__) |
120 | ||
121 | ||
05e007c1 WKG |
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.') | |
469f10e4 | 131 | |
469f10e4 | 132 | |
05e007c1 WKG |
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 | } | |
469f10e4 WKG |
138 | |
139 | ||
05e007c1 | 140 | Line 12 defines the ``setup_plugin`` function. |
469f10e4 | 141 | |
05e007c1 WKG |
142 | Line 23 defines ``hooks``. When MediaGoblin loads this file, it sees |
143 | ``hooks`` and registers all the callables with their respective hooks. | |
469f10e4 WKG |
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 plugin API for code samples and other | |
182 | things you can use when building your plugin. | |
183 | ||
184 | See `Hitchhiker's Guide to Packaging | |
185 | <http://guide.python-distribute.org/>`_ for more information on | |
186 | packaging your plugin. |