mirror of
https://github.com/Mikaela/Limnoria-doc.git
synced 2024-11-22 20:19:32 +01:00
Document plugin distribution (both traditional and the new setuptools-based one).
This commit is contained in:
parent
793e63bbdb
commit
0c3facdf75
@ -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
|
||||||
~~~~~~~~~~~~~~~~~~~~~~
|
~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
181
develop/plugin_distribution.rst
Normal file
181
develop/plugin_distribution.rst
Normal 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
|
@ -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.
|
||||||
|
|
||||||
|
Loading…
Reference in New Issue
Block a user