github/pelican
1
0
Fork 1
mirror of https://github.com/getpelican/pelican.git synced 2025-10-15 20:28:56 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions

Improve namespace plugin documentation

Browse source
This commit is contained in:
Justin Mayer 2020-06-04 11:14:37 +02:00
commit 78edd878a3
1 changed files with 15 additions and 12 deletions
Download patch file Download diff file Expand all files Collapse all files

27
docs/plugins.rst
View file

@ -10,17 +10,18 @@ How to use plugins
================== ==================
Starting with version 4.5, Pelican moved to a new plugin structure utilizing Starting with version 4.5, Pelican moved to a new plugin structure utilizing
namespace packages. Plugins supporting this structure will install under the namespace packages that can be easily installed via Pip_. Plugins supporting
namespace package ``pelican.plugins`` and can be automatically discovered this structure will install under the namespace package ``pelican.plugins`` and
by Pelican. To see a list of plugins that are active in your environment, run:: can be automatically discovered by Pelican. To see a list of plugins that are
active in your environment, run::
pelican-plugins pelican-plugins
If you leave the ``PLUGINS`` setting as default (``None``), Pelican will then If you leave the ``PLUGINS`` setting as default (``None``), Pelican will
collect the namespace plugins and register them. If on the other hand you automatically discover namespace plugins and register them. If, on the other
specify a ``PLUGINS`` settings as a list of plugins, this autodiscovery will hand, you specify a ``PLUGINS`` setting as a list of plugins, this
be disabled and only listed plugins will be registered and you will have to auto-discovery will be disabled. At that point, only the plugins you specify
explicitly list the namespace plugins as well. will be registered, and you must explicitly list any namespace plugins as well.
If you are using the ``PLUGINS`` setting, you can specify plugins in two ways. If you are using the ``PLUGINS`` setting, you can specify plugins in two ways.
The first method specifies plugins as a list of strings. Namespace plugins can The first method specifies plugins as a list of strings. Namespace plugins can
@ -54,8 +55,8 @@ the ``PLUGIN_PATHS`` list can be absolute or relative to the settings file::
Where to find plugins Where to find plugins
===================== =====================
Namespace plugins can be found in the `pelican-plugins organization`_ as Namespace plugins can be found in the `pelican-plugins organization`_ as
individual repositories. Legacy plugins are collected in the `pelican-plugins individual repositories. Legacy plugins are located in the `pelican-plugins
repository`_ and they will be slowly phased out in favor of the namespace repository`_ and will be gradually phased out in favor of the namespace
versions. versions.
.. _pelican-plugins organization: https://github.com/pelican-plugins .. _pelican-plugins organization: https://github.com/pelican-plugins
@ -111,8 +112,8 @@ empty besides the listed folders in the above structure and keep your
plugin related files contained solely in the ``pelican/plugins/myplugin`` plugin related files contained solely in the ``pelican/plugins/myplugin``
folder to avoid any issues. folder to avoid any issues.
For easily setting up the proper structure, a `cookiecutter template for To easily set up the proper structure, a `cookiecutter template for plugins`_
plugins`_ is provided. Refer to the README in the link for how to use it. is provided. Refer to that project's README for instructions on how to use it.
.. _cookiecutter template for plugins: https://github.com/getpelican/cookiecutter-pelican-plugin .. _cookiecutter template for plugins: https://github.com/getpelican/cookiecutter-pelican-plugin
@ -264,4 +265,6 @@ Adding a new generator is also really easy. You might want to have a look at
def register(): def register():
signals.get_generators.connect(get_generators) signals.get_generators.connect(get_generators)
.. _Pip: https://pip.pypa.io/
.. _pelican-plugins bug #314: https://github.com/getpelican/pelican-plugins/issues/314 .. _pelican-plugins bug #314: https://github.com/getpelican/pelican-plugins/issues/314