From 2530ef7a1f682dcd5c4386d6b66b1fb71e8cc554 Mon Sep 17 00:00:00 2001 From: Will Kahn-Greene Date: Wed, 23 May 2012 20:21:03 -0400 Subject: Split docs into siteadmin and pluginwriter guides * create initial bits for plugin writer's guide * move siteadmin stuff to site administrator's guide * rework index.rst to support multiple guides * tweak some text * move files into subdirectories I verified that this still works with html and texinfo build targets. There's still a lot of work to do, but this is a good start. --- docs/source/siteadmin/plugins.rst | 137 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 137 insertions(+) create mode 100644 docs/source/siteadmin/plugins.rst (limited to 'docs/source/siteadmin/plugins.rst') diff --git a/docs/source/siteadmin/plugins.rst b/docs/source/siteadmin/plugins.rst new file mode 100644 index 00000000..41f2970f --- /dev/null +++ b/docs/source/siteadmin/plugins.rst @@ -0,0 +1,137 @@ +========= + Plugins +========= + +GNU MediaGoblin supports plugins that 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. Once you find a plugin you like, you need +to first install it, then add it to your configuration. + +.. todo: how do you find plugins on the internet? + + +Installing plugins +================== + +Core plugins +------------ + +MediaGoblin core plugins don't need to be installed because they come +with MediaGoblin. Further, when you upgrade MediaGoblin, you will also +get updates to the core plugins. + + +Other plugins +------------- + +If the plugin is available on the `Python Package Index +`_, then you can install the plugin with pip:: + + pip install + +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 than the one + MediaGoblin is installed in. + +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 +=================== + +Configuration for a plugin goes in the subsection for that plugin. Core +plugins are documented in the administration guide. Other plugins +should come with documentation that tells you how to configure them. + +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! + directory = /srv/mediagoblin/flatpages + +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. + + +Upgrading plugins +================= + +Core plugins +------------ + +Core plugins get upgraded automatically when you upgrade MediaGoblin +because they come with MediaGoblin. + + +Other plugins +------------- + +For plugins that you install with pip, you can upgrade them with pip:: + + pip install -U + +The ``-U`` tells pip to upgrade the package. -- cgit v1.2.3 From 05d8f314c639f30a699c63e3d4f8feae9a5ba60b Mon Sep 17 00:00:00 2001 From: Will Kahn-Greene Date: Tue, 17 Jul 2012 21:14:45 -0400 Subject: [Issue 466] Implement e-z plugin disabling --- docs/source/siteadmin/plugins.rst | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) (limited to 'docs/source/siteadmin/plugins.rst') diff --git a/docs/source/siteadmin/plugins.rst b/docs/source/siteadmin/plugins.rst index 41f2970f..f5a78da7 100644 --- a/docs/source/siteadmin/plugins.rst +++ b/docs/source/siteadmin/plugins.rst @@ -135,3 +135,35 @@ For plugins that you install with pip, you can upgrade them with pip:: pip install -U The ``-U`` tells pip to upgrade the package. + + +Troubleshooting plugins +======================= + +Sometimes plugins just don't work right. When you're having problems +with plugins, think about the following: + +1. Check the log files. + + Some plugins will log errors to the log files and you can use that + to diagnose the problem. + +2. Try running MediaGoblin without that plugin. + + It's easy to disable a plugin from MediaGoblin. Add a ``-`` to the + name in your config file. + + For example, change:: + + [[mediagoblin.plugins.flatpages]] + + to:: + + [[-mediagoblin.plugins.flatpages]] + + That'll prevent the ``mediagoblin.plugins.flatpages`` plugin from + loading. + +3. If it's a core plugin that comes with MediaGoblin, ask us for help! + + If it's a plugin you got from somewhere else, ask them for help! -- cgit v1.2.3 From 7a690a5ae541f26321be98625a3df34847b44d5b Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Mon, 20 Aug 2012 08:54:09 -0500 Subject: Updated flatpages example in plugins.rst to reflect reality & point to flatpages docs --- docs/source/siteadmin/plugins.rst | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) (limited to 'docs/source/siteadmin/plugins.rst') diff --git a/docs/source/siteadmin/plugins.rst b/docs/source/siteadmin/plugins.rst index f5a78da7..594461c0 100644 --- a/docs/source/siteadmin/plugins.rst +++ b/docs/source/siteadmin/plugins.rst @@ -79,14 +79,18 @@ should come with documentation that tells you how to configure them. 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:: +for that is ``mediagoblin.plugins.flatpagesfile`` and you would add +that to your ``.ini`` file like this:: [plugins] - [[mediagoblin.plugins.flatpages]] - # configuration for flatpages plugin here! - directory = /srv/mediagoblin/flatpages + [[mediagoblin.plugins.flatpagesfile]] + # configuration for flatpagesfile plugin here! + about-view = '/about', about.html + terms-view = '/terms', terms.html + +(Want to know more about the flatpagesfile plugin? See +:ref:`flatpagesfile-chapter`) Example 2: Plugin that is not a core MediaGoblin plugin -- cgit v1.2.3 From 3a438f5e84cef433d5c396f14dec8cd8a713e93c Mon Sep 17 00:00:00 2001 From: Will Kahn-Greene Date: Mon, 20 Aug 2012 12:35:35 -0400 Subject: Docs tweaks This fixes some minor issues in the documentation. --- docs/source/siteadmin/plugins.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs/source/siteadmin/plugins.rst') diff --git a/docs/source/siteadmin/plugins.rst b/docs/source/siteadmin/plugins.rst index 594461c0..75562d4b 100644 --- a/docs/source/siteadmin/plugins.rst +++ b/docs/source/siteadmin/plugins.rst @@ -159,13 +159,13 @@ with plugins, think about the following: For example, change:: - [[mediagoblin.plugins.flatpages]] + [[mediagoblin.plugins.flatpagesfile]] to:: - [[-mediagoblin.plugins.flatpages]] + [[-mediagoblin.plugins.flatpagesfile]] - That'll prevent the ``mediagoblin.plugins.flatpages`` plugin from + That'll prevent the ``mediagoblin.plugins.flatpagesfile`` plugin from loading. 3. If it's a core plugin that comes with MediaGoblin, ask us for help! -- cgit v1.2.3 From 7989cd6e4961749a39147c9020dbae745b4f23de Mon Sep 17 00:00:00 2001 From: Sebastian Spaeth Date: Sat, 1 Dec 2012 20:31:18 +0100 Subject: docs: Add trim_whitespaces plugin to relnotes and documentation Rather than mentioning a hypothetical module restrictfive, we use the existing plugin mediagoblin-licenses that people can install. Also, mention that plugin in the release notes. Signed-off-by: Sebastian Spaeth --- docs/source/siteadmin/plugins.rst | 22 +++++++++++++--------- 1 file changed, 13 insertions(+), 9 deletions(-) (limited to 'docs/source/siteadmin/plugins.rst') diff --git a/docs/source/siteadmin/plugins.rst b/docs/source/siteadmin/plugins.rst index 75562d4b..baca381d 100644 --- a/docs/source/siteadmin/plugins.rst +++ b/docs/source/siteadmin/plugins.rst @@ -44,29 +44,33 @@ If the plugin is available on the `Python Package Index pip install For example, if we wanted to install the plugin named -"mediagoblin-restrictfive", we would do:: +"mediagoblin-licenses" (which allows you to customize the licenses you +offer for your media), we would do:: - pip install mediagoblin-restrictfive + pip install mediagoblin-licenses .. 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 than the one - MediaGoblin is installed in. + virtual environment before installing with pip. Otherwise the plugin + may get installed in a different environment than the one MediaGoblin + is installed in. Also make sure, you use e.g. pip-2.7 if your default + python (and thus pip) is python 3 (e.g. in Ubuntu). 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 +For example, say the "mediagoblin-licenses" plugin has the Python +package path ``mediagoblin_licenses``, then you would add ``mediagoblin_licenses`` to the ``plugins`` section as a subsection:: [plugins] - [[restrictfive]] + [[mediagoblin_licenses]] + license_01=abbrev1, name1, http://url1 + license_02=abbrev2, name1, http://url2 Configuring plugins @@ -112,7 +116,7 @@ Removing plugins To remove a plugin, use ``pip uninstall``. For example:: - pip uninstall mediagoblin-restrictfive + pip uninstall mediagoblin-licenses .. Note:: -- cgit v1.2.3