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

Update namespace docs to address review

Browse source
This commit is contained in:
Deniz Turgut 2019-12-01 20:21:20 +03:00
commit 8a56e1f1fa
1 changed files with 11 additions and 10 deletions
Download patch file Download diff file Expand all files Collapse all files

21
docs/plugins.rst
View file

@ -9,7 +9,7 @@ features to Pelican without having to directly modify the Pelican core.
How to use plugins How to use plugins
================== ==================
Starting with version 4.3, Pelican moved to a new plugin structure utilizing Starting with version 5.0, Pelican moved to a new plugin structure utilizing
namespace packages. Plugins supporting this structure will install under the namespace packages. Plugins supporting this structure will install under the
namespace package ``pelican.plugins`` and can be automatically discovered namespace package ``pelican.plugins`` and can be automatically discovered
by Pelican. by Pelican.
@ -21,8 +21,8 @@ be disabled and only listed plugins will be registered and you will have to
explicitly list the namespace plugins as well. explicitly list the namespace plugins as well.
If you are using ``PLUGINS`` setting, you can specify plugins in two ways. If you are using ``PLUGINS`` setting, you can specify plugins in two ways.
First method is using strings to the plugins. Namespace plugins can be The first method specifies plugins as a list of strings. Namespace plugins can
specified either by their full names (``pelican.plugins.myplugin``) or by be specified either by their full names (``pelican.plugins.myplugin``) or by
their short names (``myplugin``):: their short names (``myplugin``)::
PLUGINS = ['package.myplugin', PLUGINS = ['package.myplugin',
@ -53,7 +53,8 @@ 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 collected in the `pelican-plugins
repository`_ and they will be slowly phased out to the namespace versions. repository`_ and they will be slowly phased out in favor of the namespace
versions.
.. _pelican-plugins organization: https://github.com/pelican-plugins .. _pelican-plugins organization: https://github.com/pelican-plugins
.. _pelican-plugins repository: https://github.com/getpelican/pelican-plugins .. _pelican-plugins repository: https://github.com/getpelican/pelican-plugins
@ -86,11 +87,11 @@ which you map the signals to your plugin logic. Let's take a simple example::
your ``register`` callable or they will be garbage-collected before the your ``register`` callable or they will be garbage-collected before the
signal is emitted. signal is emitted.
Namespace Plugin structure Namespace plugin structure
-------------------------- --------------------------
Namespace plugins must adhere to a certain structure in order to function Namespace plugins must adhere to a certain structure in order to function
properly. They need to installable (i.e. contain ``setup.py`` or equivalent) properly. They need to be installable (i.e. contain ``setup.py`` or equivalent)
and have a folder structure as follows:: and have a folder structure as follows::
myplugin myplugin
@ -102,11 +103,11 @@ and have a folder structure as follows::
├── ... ├── ...
└── setup.py └── setup.py
It is crucial that ``pelican`` or ``pelican/plugins`` folder **should not** It is crucial that ``pelican`` or ``pelican/plugins`` folder **not**
contain an ``__init__.py`` file. In fact, it is best to have those folders contain an ``__init__.py`` file. In fact, it is best to have those folders
empty besides the listed folders in the above structure and contain your empty besides the listed folders in the above structure and keep your
plugin related files solely in the ``pelican/plugins/myplugin`` folder to plugin related files contained solely in the ``pelican/plugins/myplugin``
avoid any issues. folder to avoid any issues.
For easily setting up the proper structure, a `cookiecutter template for 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. plugins`_ is provided. Refer to the README in the link for how to use it.