docs/source/plugins/index.rst
Kiwi TCMS plugins
=================
You can design your own plugins which will be automatically
discovered and loaded by Kiwi TCMS. There is an example in
`tcms/telemetry/tests/plugin <https://github.com/kiwitcms/Kiwi/tree/master/tcms/telemetry/tests/plugin>`_
but these are not limited to telemetry! They can be anything!
Your plugin should be packaged as a stand-alone Django application that
can be installed *inside* Kiwi TCMS! This means to produce a pip package
containing your ``views.py``, ``urls.py``, ``templates/``, ``static/``,
etc files which are standard for Django applications.
There are 2 special pieces:
- a ``menu.py`` file defining the ``MENU_ITEMS`` variable.
The format is the same as ``tcms.settings.common.MENU_ITEMS``
- inside ``setup.py`` you need to define an ``entry_point``::
setup(
...
entry_points={"kiwitcms.plugins": ["your_plugin_name = your_plugin_module"]},
)
Kiwi TCMS will auto-discover plugins with the ``kiwitcms.plugins``
entry point and:
- append them to ``INSTALLED_APPS`` so that templates, static files and
everything else can be discovered. This means models and migrations too;
- append their menu to ``MENU_ITEMS`` under the PLUGINS navigation item
so that users can access the plugin via the web interface;
- include their URL config in ``urlpatterns``, using the plugin name as the
URL path for inclusion!
After you have tested your plugin and packaged it as a pip package the only
thing you have to do is install the tarball inside the Docker image!