How do I generate Vim documentation from Markdown notes or inline comments, or are there better ways to add documentation?

Question

This is kind of two questions in one. Lately I've been spending a lot of time learning vimscript in-depth, learning vim's internals & taking my first steps writing vim plugins. During this process, I've been keeping extensive notes in individual markdown files & add lots of inline 'documentation' comments to the vimscript files.

I feel like I've finally got some code that's worth sharing, and want to start adding some actual documentation. I haven't authored any of my own helpdoc files yet, so I'm still figuring out that process.

Without any experience yet or solid understanding of this workflow, there are two tasks I'm trying to figure out:

1. Generating helpdoc files from my markdown 'notes' files on vim/vimscript, so I can read/reference quickly & easily from vim at any time.
2. Parsing the inline documentation from my vimscript files (similar to the way shocco works for shell scripts) to generate the associated helpdoc for the vimscripts.

Any suggestions or advice on the ideas (this is a bad idea because ..., a better idea is ...), or how to accomplish them would be greatly appreciated.

Answer 1

As far as I know there is currently no good solution for either problem, but a lot of people would be interested in solving them.

Markdown is a superset of HTML, so I'd say a frontal approach to conversion from markdown to Vim help is unlikely to succeed. If you can speak Haskell you could try to write a Vim help backend for pandoc. That would be a very nice solution even if it isn't perfect.

There have been a few attempts at doing it the other way around, convert Vim help pages to some useful format. There are a few scripts floating around that produce HTML and PDF versions of the official help, with varying degrees of success. But they all rely on the help being more or less homogenous in style. Even a Vim help reader for something like pandoc would be a worthwhile project.

As for extracting documentation from Vim code, there's a parser for VimL in Python, JavaScript, and VimL itself, named vimlparser. It's pretty good, it shouldn't be hard to write something that parses VimL sources and dumps special crafted comments. Being able to convert these comments to something like, say, POD would be highly useful too.

Answer 2

html2vimdoc.py

The most promising tool I've found is html2vimdoc.py which can be found here http://peterodding.com/code/vim/tools and on github. It can convert markdown and html to vim's help format. Advertised features are:

• It can deal with complex HTML thanks to [BeautifulSoup] bs
• Automatically generates Vim help file tags for headings
• Generates table of contents from headings & tags
• Supports nested block structures like nested lists, preformatted blocks inside lists, etc.
• Compacts & expands list items based on average number of lines per list item

An older alternative is https://github.com/mklabs/vim-markdown-helpfile

There has also been a discussion on https://superuser.com/q/415470/generating-help-files-for-vim

Answer 3

There is Md2Vim project: tool for automatically converting markdown to vimdoc format.

Quotation:

Writing technical documentation for Vim extensions is not exciting; manually converting what you've just written in Markdown to vimdoc format is even less fun. I grew tired of having to do this repeatedly for my Vim-ArgWrap extension and finally formally solved this problem with a purpose-built tool. Maintainability, ease of use, and beautiful vimdoc output were primary considerations in Md2Vim's design.