A basic Pelican Plugin template to kickstart your own.
.. image:: https://travis-ci.com/nebulousdog/thedropin.svg?branch=master :target: https://travis-ci.com/nebulousdog/thedropin :alt: travis-link .. image:: https://codecov.io/gh/nebulousdog/thedropin/branch/master/graph/badge.svg :target: https://codecov.io/gh/nebulousdog/thedropin :alt: codecov-link .. image:: https://img.shields.io/pypi/v/thedropin.svg :target: https://pypi.org/project/thedropin/ :alt: pypi-link
These are the bare minimum yet possibly over-explained steps for creating a Pelican plugin.
Steps
Please let us know in an issue <https://github.com/nebulousdog/thedropin/issues>
_ if we forgot anything!
thedropin <https://github.com/nebulousdog/thedropin>
_... [1] Python project names are typically short and lower-cased. If you make a single-word project, congrats, you never have to worry about inconsistent casing between projects. If you absolutely must use spacing, use underscores for project names, directories, and filenames.
See instructions for installing Pipenv <https://github.com/pypa/pipenv#installation>
_. Then run pipenv install --dev
.
This is now where you get to get 🎨 creative! Good luck, have fun.
ETC ^^^
This is wading into dangerous territory to start recommending text-editor practices, but if you open your editor from inside the Pipenv shell, that may help your editor loading the proper environment-specific dependencies.
pipenv run tests
pipenv run lints
Two great ways to share your code with the community.
Pelican Plugins Community Repo ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
See Contributing a plugin <https://github.com/getpelican/pelican-plugins/blob/master/Contributing.rst>
_ and Using Git and Github <https://docs.getpelican.com/en/latest/contribute.html#using-git-and-github>
_ about adding a plugin to the pelican-plugins
repo <https://github.com/getpelican/pelican-plugins>
_.
Publishing to PyPI ^^^^^^^^^^^^^^^^^^
This is probably the hardest part, and is why I'd wager there are so few Pelican projects registered on PyPI[2]_. Begin with the manual steps. Afterwards, add support for the automated steps as soon as possible while everything is fresh in your head.
.. [2] This is based on the following three classifier <https://pypi.org/classifiers/>
_ searches. At the time of writing these are the tallies, with possible overlap between them; Framework :: Pelican <https://pypi.org/search/?q=&o=&c=Framework+%3A%3A+Pelican>
_ (20 projects) + Framework :: Pelican :: Plugins <https://pypi.org/search/?c=Framework+%3A%3A+Pelican+%3A%3A+Plugins>
_ (12 projects) + Framework :: Pelican :: Themes <https://pypi.org/search/?c=Framework+%3A%3A+Pelican+%3A%3A+Themes>
_ (5 projects) = 37.
First Time """"""""""
Your first time uploading a project to PyPI requires using Twine <https://github.com/pypa/twine>
. All of the below commands can be found in the Pipfile <https://github.com/nebulousdog/thedropin/blob/master/Pipfile>
[scripts]
section for your convenience.
pipenv shell
Enter your dev environment where twine
will be accessible.python setup.py sdist bdist_wheel
Create a normal distribution.Register <https://pypi.org/account/register/>
_ on PyPI.Optionally, you can do some checks on your distribution before attempting an official upload.
register <https://pypi.org/account/register/>
_ on TestPyPI if you intend to test your distribution before making it official.twine check dist/*
Check the distribution you made in the second step.twine upload --repository testpypi dist/*
Run a test of the upload. Preview at https://test.pypi.org/project/thedropin.Back to the official upload steps..
twine upload dist/*
Upload your project to PyPI.Continue below before you're tired!
Automated Release to PyPI """""""""""""""""""""""""
gem install travis
Install the Travis CLI.travis login
Log into the CLI app. Use --com
if you've opted into the https://travis-ci.com/ beta.travis encrypt "your-api-token" --com
Override the token in this repo. Travis is migrating to Travis travis-ci.com.python ./release.py
Save your changes and bump the version.Try bumping the version and tags again using the release script. After you've found your groove with this, give yourself a pat on the back. Job well done!
Installation
The installation instructions for your new plugin will now be the following.
pipenv install --dev thedropin
update your pelicanconf.py
's plugins settings to include the following.
.. code-block:: python
import thedropin PLUGINS = [thedropin]
You can now include {{ article.emoji }}
or {{ page.emoji }}
in your templates. This can be overridden in the article, or page's, metadata. For example, :emoji: 🧙
.
References
Contributing and feedback guidelines <https://docs.getpelican.com/en/latest/contribute.html>
_How to create plugins <https://docs.getpelican.com/en/latest/plugins.html#how-to-create-plugins>
_Contributing a plugin <https://github.com/getpelican/pelican-plugins/blob/master/Contributing.rst>
_License
MIT