{
 "metadata": {
  "name": "BloggingFromIPython"
 },
 "nbformat": 3,
 "nbformat_minor": 0,
 "worksheets": [
  {
   "cells": [
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "Blogging from IPython\n",
      "====================="
     ]
    },
    {
     "cell_type": "raw",
     "metadata": {},
     "source": [
      ":author: Adam <keflavich@gmail.com>\n",
      ":tags: python, blogging, meta\n",
      ":date: 2013-09-22"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "[ [Notebook Form of this post](http://nbviewer.ipython.org/urls/raw.github.com/keflavich/blog/master/content/BloggingFromIPython.ipynb) ]"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "There have been [many](http://jmcarp.github.io/blog/2013/07/07/hello-world/) [other](http://danielfrg.github.io/blog/2013/02/16/blogging-pelican-ipython-notebook/) [posts](http://danielfrg.github.io/blog/2013/03/08/pelican-ipython-notebook-plugin/) about blogging in ipython, but they all included more overhead than I really wanted to deal with."
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "Instead, I've gone directly to [the source](http://nbviewer.ipython.org/urls/raw.github.com/Carreau/posts/master/06-NBconvert-Doc-Draft.ipynb) and used nbconvert in ipython 2.0 to convert my notebooks to rst, then put them through pelican. \n",
      "\n",
      "This post outlines my workflow."
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "First, and most inconvenient, it is necessary to head any blog post with metadata.  I don't have any convenient workflow to deal with that, I just write it in by hand in a raw text box (ctrl-m, t) as you can see above.  [Daniel Rodriguez](http://danielfrg.github.io/) took a [different approach](http://danielfrg.github.io/blog/2013/03/08/pelican-ipython-notebook-plugin/) using the ipython metadata directly and an ipython plugin, but I didn't want to have to worry about installing plugins and I am definitely worried about breaking notebooks by messing with the [metadata](https://github.com/ipython/ipython/wiki/IPEP-20%3A-Informal-structure-of-cell-metadata) as the ipy devs give some fairly [strict warnings](https://gist.github.com/Carreau/4437348)."
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "Next, the ipynb -> rst step is fairly straightforward.  I modified the rst template because I don't want to see the `In[#]:` and `Out[#]:` prefixes around my code.  I also use `.. code-block::` rather than `.. code::`.  \n",
      "\n",
      "This very simple function below makes sure that my local `rst.tbl` file is seen before ipython's.  Their templates are in `IPython/nbconvert/templates`.  Note that you could normally use Jinja2 templating and \"Extend\" their template, but I wanted to remove rather than extend.  \n",
      "\n",
      "[ [Source](https://github.com/keflavich/blog/blob/master/nbconverter.py) ]"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": true,
     "input": [
      "from IPython.nbconvert.exporters import RSTExporter\n",
      "\n",
      "def export(nbname, outfilename=None):\n",
      "    exportRST = RSTExporter()\n",
      "    # exclude default paths\n",
      "    exportRST.template_path = ['.','/Users/adam/repos/blog'] \n",
      "\n",
      "    (body,resources) = exportRST.from_filename(nbname)\n",
      "\n",
      "    if outfilename is None:\n",
      "        outfilename = nbname.replace(\"ipynb\",\"rst\")\n",
      "\n",
      "    with open(outfilename,'w') as f:\n",
      "        f.write(body)\n",
      "\n",
      "    return body,resources"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "I then run the script from the command line:\n",
      "    `~/virtual-ipydev/bin/ipython ./nbconverter.py content/GenerateCVExample.ipynb`\n",
      "    \n",
      "I'm using a virtual environment with ipython 2 installed because I'm not yet ready to make the jump to the dev version of ipython (though these days, with Travis and Jenkins around, it's probably safe to assume the dev version won't break anything).\n",
      "\n",
      "With this rst file generated, the only remaining step is [pelican](http://blog.getpelican.com/), which only requires a `make github` command in the blog directory.  Installing & setting up pelican is reasonably easy, but not the topic of this post."
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "I've made my own [custom pelican theme](https://github.com/keflavich/pelican-themes/tree/master/mine), so I generally need to update the theme before building:\n",
      "\n",
      "`pelican-themes --upgrade /Users/adam/repos/pelican-themes/mine && make github`"
     ]
    }
   ],
   "metadata": {}
  }
 ]
}