I’m a programmer which naturally means I hate performing repetitive tasks… Publishing my Vim plug-ins quickly turned out to fall in this category; I’d keep making the same mistakes and having users e-mail me because I screwed up again and uploaded a broken release to www.vim.org. After a while this got embarrassing so I decided to solve this annoying problem once and for all.
Things started out small but as my existing Vim plug-ins mature and I publish
more Vim plug-ins to the world, the
vim-tools repository grows with me. It
now contains several Python modules which can be useful to other people (mostly
Vim plug-in developers) which is why I’m sharing it with the world.
The Python module
html2vimdoc.py converts Markdown and HTML documents
to Vim help files.
It has a command line interface but can also be used as a plain Python module.
html2vimdoc.py module has several dependencies, the easiest way to
install them is in a Python virtual environment:
# Clone the repository git clone https://github.com/xolox/vim-tools.git cd vim-tools # Create the virtual environment. virtualenv html2vimdoc # Install the dependencies. html2vimdoc/bin/pip install beautifulsoup coloredlogs markdown # Run the program. html2vimdoc/bin/python ./html2vimdoc.py --help
I use this module to convert my Vim plug-in
README.md files and the Lua, LPeg and Lua/APR manuals to Vim’s help file format.
Here’s my workflow involving the documentation of my Vim plug-ins:
README.mdfiles because GitHub renders such files as a “repository homepage”.
README.mdfile to a Vim help file which is included in the commit.
README.mdis fetched and used as the plug-in homepage on my website.
The Python module
vimdoctool.py extracts the public functions and related
comments (assumed to contain text in Markdown format) from the Vim
scripts in and/or below the current working directory. The extracted
documentation is combined into one chunk of text and then this chunk of text is
embedded in the Markdown document given on the command line.
I use this module to publish the documentation of my vim-misc scripts.
This module has a dependency on my coloredlogs module which is available on PyPi (the Python package index).
This program (written in Python) makes it easier for me to publish my Vim plug-ins on GitHub and Vim Online. It automates most of my release management, here’s a short summary:
doc/tagsis included in
README.mdis up to date
vimdoctool.pyto update function documentation embedded in
html2vimdoc.pyto update Vim help file based on
git archiveis used to generate a ZIP archive with a clean copy (no local changes) of the last commit
It might be a bit specific to my workflow but you never know, someone might find it useful :-)
If you have questions, bug reports, suggestions, etc. the author can be contacted at firstname.lastname@example.org. The latest version is available at http://peterodding.com/code/vim/tools/ and http://github.com/xolox/vim-tools.
This software is licensed under the MIT license.
© 2013 Peter Odding <email@example.com>.
html2vimdoc.py module bundles
soupselect.py by Simon Willison. The
soupselect module is also licensed under the MIT license. You can find
the soupselect module on GitHub and Google Code.
Last updated Wed Apr 01 21:09:12 UTC 2015.