A small but useful tip today, on using iPython notebooks for a git project README while keeping an auto-generated version in the Markdown format that Github prefers.
I’m in the midst of refreshing and updating the HTRC Feature Reader library. Since the README for that project walks you through the tool and sample output, I converted it to an iPython notebook: it’s easier to maintain and easier for some people to try it themselves.
While Github now formats iPython notebooks properly, it only does so when viewed directly, making it useless for a landing page (e.g. See how the raw text is shown in this repository).
My solution was to automatically generate the ‘pretty’ Markdown version that Github prefers, using git hooks and iPython’s nbconvert command. Git hooks allow you to hook in client-side or server-side scripts before or after various git actions, like pre-commit, post-checkout, pre-rebase, etc.
The Notebook-to-Markdown conversion script runs post-commit* by adding the following code to .git/hooks/post-commit:
This code checks if README.ipynb was committed without README.md. If it has, it generates the latter and amends the previous commit. If you want to commit a file without the check, you can always run git commit with –no-verify.
By the way, if you’re looking for a way to only track substantial iPython Notebook changes in git, this tip works for me.
*Why post-commit and not pre-commit? It seems that at pre-commit, newer installs of Git don’t allow you to git add to commit you’re adding to: the file ends up staged.