You can find quite a few Emacs libraries on github these days. I only have one very small project there, wpmail, which I haven’t written about yet because I want to finish the Markdown support first… anyway: something I find really neat on github is the automatic display of the README file in the repository’s root directory, if it exists. Only, as we all know, writing READMEs is tedious and we’d rather spend our time programming. But wait: in the Emacs world, we’re actually writing a README for each project: the library headers. Their content and structure are rather clearly defined, and it’s expected for all Emacs libraries. So I had the idea of generating a nice, Markdown-formatted README.md for github from these headers.
I just pushed the first version of md-readme that does just that. The README that you see on the github page is auto-generated from md-readme.el, with lists, code-block and everything.
The conversion to Markdown is of course pretty simple, but even so it’s pretty cool to see how little code I had to write. Emacs provides everything out of the box.
(with-temp-file "README.md" (do-it)) is just elegant.
Now, seeing that we have code that generates a nice README from our Lisp file, it’s natural to have it run automatically so we always have an up-to-date README. Here I was struggling for a while. I had lots of ideas, but none seemed to work out. My current solution is setting a per-directory local variable for each of your ELisp projects that triggers the conversion via an after-save-hook. Code is in the README. The problem with adding the after-save-hook to all modes is that it’s evaluated all the time, for each save. Kinda annoying, even if it’s just a single condition.
Does anyone have a better idea? Do it outside Emacs in a git pre-commit hook?
But even with the current solution it works, and that’s the important part. Please try it, and enjoy your new READMEs.