Document plugin distribution (both traditional and the new setuptools-based one).

This commit is contained in:
Valentin Lorentz 2020-05-08 19:17:42 +02:00
parent 793e63bbdb
commit 0c3facdf75
3 changed files with 185 additions and 3 deletions

View File

@ -15,6 +15,7 @@ Generic documentation
style.rst style.rst
advanced_plugin_config.rst advanced_plugin_config.rst
advanced_plugin_testing.rst advanced_plugin_testing.rst
plugin_distribution.rst
Specific documentation Specific documentation
~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~

View File

@ -0,0 +1,181 @@
.. _distributing-plugins:
********************
Distributing plugins
********************
Now that you wrote a plugin, you may want to share it with other people.
There are many way to do this, and we are going to present some of them
below.
Via a VCS repository
====================
If you already use a VCS (such as Git, Mercurial, or Subversion), giving
access to your repository is the easiest way for you to share your plugins.
This method can also easily be adapted to distribute tarballs.
It will however require a little more work for your users.
There are two ways to do it:
With a single plugin per repository
-----------------------------------
By initializing a repository in each folder created by `supybot-plugin-wizard`
(eg. with `git init`).
This allows you to keep each plugin's history independent.
First, users should install a client for your VCS, and dependencies of
your plugin, if any.
Users can then download and install your plugin in a single command::
cd runbot/plugins/
git clone https://example.org/~jdoe/YourPlugin.git
(or the equivalent for your VCS)
and then immediately run ``@load YourPlugin``.
With all your plugins in the same repository
--------------------------------------------
By running ``git init`` in a new folder, then call ``supybot-plugin-wizard`` in this
folder to create each plugin in a subdirectory.
This is the easiest for your if you maintain many plugins, as you don't have
to manage many repositories.
First, users should install a client for your VCS, and dependencies of
your plugin(s) they want to use, if any.
Users can download all your plugins at once::
cd ~/
git clone https://example.org/~jdoe/LimnoriaPlugins.git JdoePlugins
and configure their bot to look for plugins in this directory::
@config supybot.directories.plugins [config supybot.directories.plugins], /home/me/JdoePlugins
Alternatively, to make it easier for your users, you can add your repository
to Limnoria's list of known repository, by sending a pull request to:
https://github.com/ProgVal/Limnoria/blob/master/plugins/PluginDownloader/plugin.py
.. note::
PluginDownloader currently only works on GitHub, but pull requests to add
support for other forges are welcome.
Once it is accepted, users can then download your plugin in a single step
instead of the commands above::
@plugindownloader install Jdoe
Either way, they can now run ``@load YourPlugin``
Via pip / PyPI
==============
This requires a little more work for you, but uses mainstream Python package
management (pip/PyPI) so it is a lot easier for users (as they don't have to
use a VCS, put your plugin in the right directory, or install dependencies
manually)
.. warning::
This distribution method is currently experimental, but will likely be the
recommended one some time in the future.
Please try it out and give us feedback on #limnoria at freenode!
Setting up your plugin
----------------------
To make your plugin installable via pip, you first need to create a ``setup.py``
file in the same directory as the other files of your plugin.
You have probably seen one already if you are a Python developer.
Limnoria provides a small wrapper over ``setuptools.setup``, so you don't have
to type in most of the fields.
The minimal ``setup.py`` for a plugin named ``YourPlugin`` is::
from supybot.setup import plugin_setup
plugin_setup(
'YourPlugin',
)
This will automatically populate:
* the package name (``name = "limnoria-yourplugin"``)
* author information (``author`` and ``author_email`` if they are set in ``__init__.py``)
* maintainer information (idem)
* version and URL (based on ``__version__`` and ``__url__`` in ``__init__.py``)
* ``package = "limnoria_yourplugin"``
* ``package_dirs = {"limnoria_yourplugin": "."}``
* add Limnoria as dependency
* etc.
You can add any setuptools fields you like.
For example, to add ``requests`` as a dependency::
from supybot.setup import plugin_setup
plugin_setup(
'YourPlugin',
install_requires=[
'requests',
],
)
If you don't like the name `limnoria-yourplugin`, you can also override it.
For example::
from supybot.setup import plugin_setup
plugin_setup(
'YourPlugin',
name='limnoria-this-is-my-plugin',
)
Publishing your plugin
----------------------
It's now time to publish your plugin to PyPI.
First, you must create an account on https://pypi.org/ and install twine::
python3 -m pip install --user --upgrade twine
Then, you can generate and publish your plugin::
python3 -m twine sdist
python3 -m twine upload dist/*
And every time you want to publish an upgrade, update the version
in ``__init__.py`` and run this last command again.
For more details, see the official Python documentation on:
* `generating archives <https://packaging.python.org/tutorials/packaging-projects/#generating-distribution-archives>`_
* `uploading archives <https://packaging.python.org/tutorials/packaging-projects/#uploading-the-distribution-archives>`_
Installing plugins
------------------
Finally, once you installed your plugin, users can install it simply with::
sudo pip3 install limnoria-yourplugin
and this will automatically install your plugin's dependencies as well. Then,
they just need to run ``@load YourPlugin`` as usual.
Alternatively, if you don't want to publish on PyPI, they can still
use pip to install directly from your repository, for example::
sudo pip3 install git+https://example.org/~jdoe/YourPlugin.git

View File

@ -553,9 +553,9 @@ wisdom with regards to Supybot plugin-writing.
first point above, the developers themselves can help you even more than first point above, the developers themselves can help you even more than
the docs can (though we prefer you read the docs first). the docs can (though we prefer you read the docs first).
* Share your plugins with the world and make Supybot all that more * :ref:`Share your plugins with the world <distributing-plugins>`
attractive for other users so they will want to write their plugins for and make Supybot all that more attractive for other users so they will want
Supybot as well. to write their plugins for Supybot as well.
* Read, read, read all the documentation. * Read, read, read all the documentation.