Skip to content

Commit

Permalink
Documentation updates for Lektor PR lektor/lektor#1065
Browse files Browse the repository at this point in the history
  • Loading branch information
@dairiki
dairiki committed Sep 7, 2022
1 parent 011af60 commit bd0dc49
Show file tree
Hide file tree
Showing 2 changed files with 95 additions and 86 deletions.
56 changes: 34 additions & 22 deletions content/docs/plugins/dev/contents.lr
View file
Original file line number Diff line number Diff line change
Expand Up @@ -44,45 +44,57 @@ package in the packages folder.

Alternatively you can manually create a `packages/hello-world/` folder.

Once that is done, we need to create a `setup.py` file which tells Lektor
what your plugin needs to run. This will already be created for you if
you used the wizard.
Once that is done, we need to create `pyproject.toml` and `setup.cfg` files.
These files tell the python packaging tools what your plugin needs to run
and tell Lektor how to run your plugin. These files will already have been created
for you if you used the `lektor dev new-plugin` wizard.

! Note that these days there are many different tools that can be used to build
distributions (and even more ways to configure those tools.) Since Lektor version 3.4,
you may use any packaging tool that supports PEP-517 and PEP-660.

`pyproject.toml`
```toml
[build-system]
requires = ["setuptools>=45"]
build-backend = "setuptools.build_meta"
```

`setup.cfg`
```ini
[metadata]
name = lektor-hello-world
version = 0.1

[options]
py_modules = lektor_hello_world
install_requires =

[options.entry_points]
lektor.plugins =
hello-world = lektor_hello_world:HelloWorldPlugin

```python
from setuptools import setup

setup(
name='lektor-hello-world',
version='0.1',
py_modules=['lektor_hello_world'],
entry_points={
'lektor.plugins': [
'hello-world = lektor_hello_world:HelloWorldPlugin',
]
},
install_requires=[]
)
```

So going line by line, these are what the things mean:

* `setuptools` is a module that helps us install the package with the
Python interpreter that Lektor uses. We only need the setup function
from it for this example.
* `setuptools` is a package that helps us install the package with the
Python interpreter that Lektor uses. The above `pyproject.toml` declares
that we are using setuptools to build and install our plugin.
* `name` is the name of the plugin when it's published to the Python package
index where all Lektor plugins go. As such it should be prefixed with
`lektor-` to make it not clash with other packages on the index.
* `version` identifies the version. During local development it does not
matter what you write here, but it will play a role once you start
publishing your packages. Users need to reference exact versions of these
plugins when using them.
* `py_modules`: this is a list of modules that your plugin needs to run.
* `py_modules`: this is a list of modules that are part of your plugin's _distribution_.
This should always be exactly one module named `lektor_XXX` where `XXX`
is your plugin name with underscores instead of dashes as separators.
If you need more than one module you should use a package instead. This is
not covered here, but you can find this in the [setuptools documentation
:ext](https://setuptools.pypa.io/en/latest/).
* `entry_points`: this is meta data that is needed to associate our package
* `entry_points`: this is metadata that is needed to associate our package
with Lektor. Lektor will load all plugins in the `lektor.plugins` list.
It can be a list of definitions in the form `plugin-name = import_path`.
The plugin name is what will show up in the plugin list in Lektor,
Expand Down
125 changes: 61 additions & 64 deletions content/docs/plugins/publishing/contents.lr
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,79 +8,76 @@ 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
automatically done with the help of the lektor shell command.
[Python Package Index :ext](https://pypi.org/).

## Enhance your setup.py

## Enhance your setup.cfg

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`:

```python
import ast
import io
import re

from setuptools import setup, find_packages

with io.open('README.md', 'rt', encoding="utf8") as f:
readme = f.read()

_description_re = re.compile(r'description\s+=\s+(?P<description>.*)')

with open('lektor_hello_world.py', 'rb') as f:
description = str(ast.literal_eval(_description_re.search(
f.read().decode('utf-8')).group(1)))

setup(
author='Your Name',
author_email='your.email@your.domain.invalid',
description=description,
keywords='Lektor plugin static-site blog',
license='MIT',
long_description=readme,
long_description_content_type='text/markdown',
name='lektor-hello-world',
packages=find_packages(),
py_modules=['lektor_hello_world'],
url='http://github.com/youruser/lektor-yourplugin',
version='1.0',
classifiers=[
'Framework :: Lektor',
'Environment :: Web Environment',
'Environment :: Plugins',
'License :: OSI Approved :: MIT License',
],
entry_points={
'lektor.plugins': [
'hello-world = lektor_hello_world:HelloWorldPlugin',
]
}
)
some information added about it to your `setup.cfg` (or whatever file it is
you use to configure your distributions metadata — other files where metadata
may be declared include `setup.py` and/or `pyproject.toml`). At least the keys
`name`, `version`, `author`, `author_email`, `url` and `description` should to be
set. Here is an example of doing this, largely taken from the `setup.cfg` which
is generated by the
[`lektor dev new-plugin`](https://www.getlektor.com/docs/plugins/dev/#creating-a-package "See: Creating a Package")
sub-command.

```ini
[metadata]
name = lektor-hello-world
version = 1.0
description = This is a simple demo Lektor plugin
url = http://github.com/youruser/lektor-yourplugin
author = Your Name
author_email = your.email@example.com
license = MIT
keywords = Lektor plugin static-site blog
long_description = file: README.md
long_description_content_type = text/markdown
classifiers =
Framework :: Lektor
Environment :: Plugins
Environment :: Web Environment
License :: OSI Approved :: MIT License

[options]
py_modules = lektor_hello_world

[options.entry_points]
lektor.plugins =
hello-world = lektor_hello_world:HelloWorldPlugin
```

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.
This is not the most basic `setup.cfg` that is strictly necessary, but instead a more full, closer-to-ideal `setup.cfg` that will help your plugin be discovered and understood most easily. Note that it assumes there is a `README.md` file.


## 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.
Once you augmented your `setup.cfg` you can go ahead publishing your new plugin to [PyPI :ext](https://pypi.org/ "The Python Package Index").
Detailed instructions on how to do this may be found in the [Packaging Tutorial :ext](https://packaging.python.org/en/latest/tutorials/packaging-projects/)
(which is part of the [Python Packaging User Guide :ext](https://packaging.python.org/en/latest/)).

The general steps involved are:

1. Create an account on PyPI (if you do not already have one.)

2. Install the latest versions of `build` and `twine` into a virtualenv.
```sh
pip install --upgrade build twine
```
3. Build the distribution, the upload it to PyPI
```sh
cd /path/to/your/plugin
# clean out any old built distribution
rm -r dist
# Build a wheel and sdist (dist/*.whl, dist/*.tar.gz)
python -m build
# Upload your newly built distribution files
python -m twine upload dist/*
```

! Note that the `lektor dev publish-plugin` sub-command has been removed as of Lektor version 3.4.

## Listing on this site

Expand Down

0 comments on commit bd0dc49

Please sign in to comment.