29b6f91740
* implements installing, loading and setup for plugins * codifies configuration * has a sample plugin * docs * tests
106 lines
3.0 KiB
ReStructuredText
106 lines
3.0 KiB
ReStructuredText
=========
|
|
Plugins
|
|
=========
|
|
|
|
GNU MediaGoblin supports plugins that, when installed, allow you to
|
|
augment MediaGoblin's behavior.
|
|
|
|
This chapter covers discovering, installing, configuring and removing
|
|
plugins.
|
|
|
|
|
|
Discovering plugins
|
|
===================
|
|
|
|
MediaGoblin comes with core plugins. Core plugins are located in the
|
|
``mediagoblin.plugins`` module of the MediaGoblin code. Because they
|
|
come with MediaGoblin, you don't have to install them, but you do have
|
|
to add them to your config file if you're interested in using them.
|
|
|
|
You can also write your own plugins and additionally find plugins
|
|
elsewhere on the Internet. Since these plugins don't come with
|
|
MediaGoblin, you must first install them, then add them to your
|
|
configuration.
|
|
|
|
|
|
Installing plugins
|
|
==================
|
|
|
|
MediaGoblin core plugins don't need to be installed. For core plugins,
|
|
you can skip installation!
|
|
|
|
If the plugin is not a core plugin and is packaged and available on
|
|
the Python Package Index, then you can install the plugin with pip::
|
|
|
|
pip install <plugin-name>
|
|
|
|
For example, if we wanted to install the plugin named
|
|
"mediagoblin-restrictfive", we would do::
|
|
|
|
pip install mediagoblin-restrictfive
|
|
|
|
.. Note::
|
|
|
|
If you're using a virtual environment, make sure to activate the
|
|
virtual environment before installing with pip. Otherwise the
|
|
plugin may get installed in a different environment.
|
|
|
|
Once you've installed the plugin software, you need to tell
|
|
MediaGoblin that this is a plugin you want MediaGoblin to use. To do
|
|
that, you edit the ``mediagoblin.ini`` file and add the plugin as a
|
|
subsection of the plugin section.
|
|
|
|
For example, say the "mediagoblin-restrictfive" plugin had the Python
|
|
package path ``restrictfive``, then you would add ``restrictfive`` to
|
|
the ``plugins`` section as a subsection::
|
|
|
|
[plugins]
|
|
|
|
[[restrictfive]]
|
|
|
|
|
|
Configuring plugins
|
|
===================
|
|
|
|
Generally, configuration goes in the ``.ini`` file. Configuration for
|
|
a specific plugin, goes in a subsection of the ``plugins`` section.
|
|
|
|
Example 1: Core MediaGoblin plugin
|
|
|
|
If you wanted to use the core MediaGoblin flatpages plugin, the module
|
|
for that is ``mediagoblin.plugins.flatpages`` and you would add that
|
|
to your ``.ini`` file like this::
|
|
|
|
[plugins]
|
|
|
|
[[mediagoblin.plugins.flatpages]]
|
|
# configuration for flatpages plugin here!
|
|
|
|
Example 2: Plugin that is not a core MediaGoblin plugin
|
|
|
|
If you installed a hypothetical restrictfive plugin which is in the
|
|
module ``restrictfive``, your ``.ini`` file might look like this (with
|
|
comments making the bits clearer)::
|
|
|
|
[plugins]
|
|
|
|
[[restrictfive]]
|
|
# configuration for restrictfive here!
|
|
|
|
Check the plugin's documentation for what configuration options are
|
|
available.
|
|
|
|
|
|
Removing plugins
|
|
================
|
|
|
|
To remove a plugin, use ``pip uninstall``. For example::
|
|
|
|
pip uninstall mediagoblin-restrictfive
|
|
|
|
.. Note::
|
|
|
|
If you're using a virtual environment, make sure to activate the
|
|
virtual environment before uninstalling with pip. Otherwise the
|
|
plugin may get installed in a different environment.
|