lektor-website/content/docs/plugins/publishing/contents.lr

102 lines
3.7 KiB
Plaintext
Raw Normal View History

2015-12-19 14:52:17 +01:00
title: Publishing
---
summary: Explains how publishing of plugins works.
---
sort_key: 20
---
body:
Once you are happy with a plugin you can publish it so that other people
can use it. Publishing of plugins happens through the
[Python Package Index :ext](https://pypi.org/) and can be
2015-12-19 14:52:17 +01:00
automatically done with the help of the lektor shell command.
## Enhance your setup.py
Before you can go about publishing your plugin there needs to be at least
some information added about it to your `setup.py`. At least the keys
`name`, `version`, `author`, `author_email`, `url` and `description` need to be
set. Here is an example of doing this, largely taken from what is given by
the CLI command `lektor dev new-plugin`:
2015-12-19 14:52:17 +01:00
```python
import ast
import io
import re
2015-12-19 14:52:17 +01:00
from setuptools import setup, find_packages
with io.open('README.md', 'rt', encoding="utf8") as f:
readme = f.read()
2015-12-19 14:52:17 +01:00
_name_re = re.compile(r'name\s+=\s+(?P<name>.*)')
_description_re = re.compile(r'description\s+=\s+(?P<description>.*)')
with open('lektor_dsdf.py', 'rb') as f:
name = str(ast.literal_eval(_name_re.search(
f.read().decode('utf-8')).group(1)))
with open('lektor_dsdf.py', 'rb') as f:
description = str(ast.literal_eval(_description_re.search(
f.read().decode('utf-8')).group(1)))
2015-12-19 14:52:17 +01:00
setup(
author='Your Name',
author_email='your.email@your.domain.invalid',
description=description,
keywords='Lektor plugin',
2015-12-19 14:52:17 +01:00
license='MIT',
long_description=readme,
long_description_content_type='text/markdown',
name=name,
packages=find_packages(),
py_modules=['lektor_hello_world'],
url='http://github.com/youruser/lektor-yourplugin',
version='1.0',
classifiers=[
'Framework :: Lektor',
'Environment :: Plugins',
],
2015-12-19 14:52:17 +01:00
entry_points={
'lektor.plugins': [
'hello-world = lektor_hello_world:HelloWorldPlugin',
]
}
2015-12-19 14:52:17 +01:00
)
```
This is not the most basic `setup.py` that is strictly necessary, but instead a more full, ideal `setup.py` that will help your plugin be discovered and and understood most easily. Note that is assumes there is a `README.md` file, and that `name` and `description` are defined in your plugin's `.py` module file, which is their preferred location for Lektor.
2015-12-19 14:52:17 +01:00
## Publishing
Once you augmented your `setup.py` you can go ahead with the publishing. First
you need to make sure you have a PyPI account. If you do not, you can
create one at [pypi.python.org :ext](https://pypi.python.org/pypi?%3Aaction=register_form).
Once you have done that, you can publish the plugin from the command line
with the `lektor` command:
```
$ cd path/to/your/plugin
$ lektor dev publish-plugin
```
When you use this for the first time it will prompt you for your login
credentials for `pypi`. Next time it will have remembered them.
## Listing on this site
We'd love to see your new plugin listed on [our plugins page :ref](/plugins). To do that, submit a pull request to [this repository :ext](https://github.com/lektor/lektor-website) that adds your plugin as a sub-page of /plugins. To have your plugin page look it's best and be found more easily here and on [PyPI :ext](https://pypi.org/), please [fill out your setup.py :ext](https://packaging.python.org/tutorials/distributing-packages/) completely (as in [the above snippet :ref](/docs/plugins/publishing/#enhance-your-setup.py)), including
* `author` and `author_email`
* `classifiers`, such as
* `Framework :: Lektor`
* `Environment :: Plugins`
* `keywords`
* `long_description` and `long_description_content_type`
* `project_urls` (optional)
* `url` to link to your repository
The `long_description` can be set to be your `README.md` file, and is especially important. Without it, your plugin's page will look a little sparse.