Websites
/
lektor-website
mirror of https://github.com/lektor/lektor-website.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Documentation updates for Lektor PR lektor/lektor#1065

This commit is contained in:
Jeff Dairiki 2022-09-06 18:26:33 -07:00
parent 8e2b686ec2
commit 451c907c69
2 changed files with 88 additions and 79 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

54
content/docs/plugins/dev/contents.lr
View File

@ -44,31 +44,43 @@ package in the packages folder.
Alternatively you can manually create a `packages/hello-world/` 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 Once that is done, we need to create `pyproject.toml` and `setup.cfg` files.
what your plugin needs to run. This will already be created for you if These files tell the python packaging tools what your plugin needs to run
you used the wizard. 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.
```python ! Note that these days there are many different tools that can be used to build
from setuptools import setup 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
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: So going line by line, these are what the things mean:
* `setuptools` is a module that helps us install the package with the * `setuptools` is a package that helps us install the package with the
Python interpreter that Lektor uses. We only need the setup function Python interpreter that Lektor uses. The above `pyproject.toml` declares
from it for this example. 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 * `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 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. `lektor-` to make it not clash with other packages on the index.
@ -76,13 +88,13 @@ So going line by line, these are what the things mean:
matter what you write here, but it will play a role once you start 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 publishing your packages. Users need to reference exact versions of these
plugins when using them. 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` This should always be exactly one module named `lektor_XXX` where `XXX`
is your plugin name with underscores instead of dashes as separators. 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 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 not covered here, but you can find this in the [setuptools documentation
:ext](https://setuptools.pypa.io/en/latest/). :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. 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`. 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, The plugin name is what will show up in the plugin list in Lektor,

113
content/docs/plugins/publishing/contents.lr
View File

@ -8,79 +8,76 @@ body:
Once you are happy with a plugin you can publish it so that other people Once you are happy with a plugin you can publish it so that other people
can use it. Publishing of plugins happens through the can use it. Publishing of plugins happens through the
[Python Package Index :ext](https://pypi.org/) and can be [Python Package Index :ext](https://pypi.org/).
automatically done with the help of the lektor shell command.
## Enhance your setup.py
## Enhance your setup.cfg
Before you can go about publishing your plugin there needs to be at least 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 some information added about it to your `setup.cfg` (or whatever file it is
`name`, `version`, `author`, `author_email`, `url` and `description` need to be you use to configure your distributions metadata — other files where metadata
set. Here is an example of doing this, largely taken from what is given by may be declared include `setup.py` and/or `pyproject.toml`). At least the keys
the CLI command `lektor dev new-plugin`: `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.
```python ```ini
import ast [metadata]
import io name = lektor-hello-world
import re 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
from setuptools import setup, find_packages [options]
py_modules = lektor_hello_world
with io.open('README.md', 'rt', encoding="utf8") as f: [options.entry_points]
readme = f.read() lektor.plugins =
hello-world = lektor_hello_world:HelloWorldPlugin
_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',
]
}
)
``` ```
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 ## Publishing
Once you augmented your `setup.py` you can go ahead with the publishing. First Once you augmented your `setup.cfg` you can go ahead publishing your new plugin to [PyPI :ext](https://pypi.org/ "The Python Package Index").
you need to make sure you have a PyPI account. If you do not, you can Detailed instructions on how to do this may be found in the [Packaging Tutorial :ext](https://packaging.python.org/en/latest/tutorials/packaging-projects/)
create one at [pypi.python.org :ext](https://pypi.python.org/pypi?%3Aaction=register_form). (which is part of the [Python Packaging User Guide :ext](https://packaging.python.org/en/latest/)).
Once you have done that, you can publish the plugin from the command line The general steps involved are:
with the `lektor` command:
``` 1. Create an account on PyPI (if you do not already have one.)
$ cd path/to/your/plugin
$ lektor dev publish-plugin
```
When you use this for the first time it will prompt you for your login 2. Install the latest versions of `build` and `twine` into a virtualenv.
credentials for `pypi`. Next time it will have remembered them. ```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 ## Listing on this site