weeheavy/pelican-theme
1
0
Fork 0
forked from github/pelican
Code Pull requests Activity

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
namespace packages. Plugins supporting this structure will install under the
namespace package ``pelican.plugins`` and can be automatically discovered
by Pelican. To see a list of plugins that are active in your environment, run::
namespace packages that can be easily installed via Pip_. Plugins supporting
this structure will install under the namespace package ``pelican.plugins`` and
can be automatically discovered by Pelican. To see a list of plugins that are
active in your environment, run::
pelican-plugins
If you leave the ``PLUGINS`` setting as default (``None``), Pelican will then
collect the namespace plugins and register them. If on the other hand you
specify a ``PLUGINS`` settings as a list of plugins, this autodiscovery will
be disabled and only listed plugins will be registered and you will have to
explicitly list the namespace plugins as well.
If you leave the ``PLUGINS`` setting as default (``None``), Pelican will
automatically discover namespace plugins and register them. If, on the other
hand, you specify a ``PLUGINS`` setting as a list of plugins, this
auto-discovery will be disabled. At that point, only the plugins you specify
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.
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
=====================
Namespace plugins can be found in the `pelican-plugins organization`_ as
individual repositories. Legacy plugins are collected in the `pelican-plugins
repository`_ and they will be slowly phased out in favor of the namespace
individual repositories. Legacy plugins are located in the `pelican-plugins
repository`_ and will be gradually phased out in favor of the namespace
versions.
.. _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``
folder to avoid any issues.
For easily setting up the proper structure, a `cookiecutter template for
plugins`_ is provided. Refer to the README in the link for how to use it.
To easily set up the proper structure, a `cookiecutter template for plugins`_
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
@ -264,4 +265,6 @@ Adding a new generator is also really easy. You might want to have a look at
def register():
signals.get_generators.connect(get_generators)
.. _Pip: https://pip.pypa.io/
.. _pelican-plugins bug #314: https://github.com/getpelican/pelican-plugins/issues/314