Technical Notes

In the past I’ve used IPython/Jupyter notebooks for literate programming, but writing code in the browser is not a great experience and I was having terrible environment issues. I started looking at alternatives, and settled on trying out pweave. It’s the same idea as IPython, allowing me to intersperse code and output with prose, but rather than using the browser I can use a standard programming editor. (It also solves my environment problem.)

The setup for getting a pweave workflow that still has all the nice parts of an IPython notebook is a little involved, so here’s what I did:

• Get the Atom editor (I generally use Sublime Text, but it can’t run Python inline)

• Set up a virtualenv and pip install "ipython[notebook]" Pweave

• Install the following Atom packages:
  • hydrogen
  • expand-region
  • language-weave
  • set-syntax (not strictly necessary, but allows me to use the cmd-shift-p to change the current document’s syntax highlighting like can be done in Sublime)
• Make the following configuration changes:

  • Append to styles.less:

    // Hydrogen output - font size is too small  
    .hydrogen.output-bubble pre {  
      font-size: 16px !important;  
    }
    // Hydrogen - hack for 2x images  
    .hydrogen.output-bubble .bubble-result-container img {  
      width: 50% !important  
    }
    

  • Append to config.cson:

    ".md.pweave.source":  
      "expand-region":  
        commands: [  
          {
            command: "expand-region:select-inside-back-ticks"  
            recursive: true  
          }
        ]
    

  • Append to keymap.cson:

    '.platform-darwin atom-text-editor':  
      'cmd-enter': 'hydrogen:run',  
      'cmd-shift-space': 'expand-region:expand'
    

  • In the settings under Settings > Packages > Hydrogen:

    • Kernel Mappings (this enables support for .pmd files): {"pweave markdown": "Python 2"}

    • Startup Code:

      {"Python 2": "import matplotlib as matplotlib_import_only\nmatplotlib_import_only.use('Agg')\n%matplotlib inline\n%config InlineBackend.figure_format = 'retina'\npython=None"}
      

      This does a few hacky things:

      • import matplotlib as matplotlib_im ... rt_only.use('Agg'): fix for this issue with a bouncing rocketship dock icon
      • %matplotlib inline: display figures inside Atom rather than in a separate window
      • %config InlineBackend.figure_format = 'retina': turns on high-resolution figures, which are displayed by Atom as double-sized low-resolution figures without the hack in styles.less above
      • python=None: a hack to avoid an error when automatically selecting and running a block of Python code

Some of this configuration is necessary to just get hydrogen to run Python code.

The rest fixes a major problem with pweave: it’s easy to run one line of code, and it’s easy to run all the code in a file, but how do I run only one block of code? (This is equivalent to being able to running an entire cell in IPython with shift-enter.)

The solution is to use the expand-region plugin to select the current block of code, and the python=None hack to avoid an error when it selects the “python” in ```python.

Here’s what it looks like in action:

To convert the .pmd file to a .html that can be shared, simply run pweave -f md2html test.pmd. Here's what the output from the above example looks like.

Notes

• Remember to open Atom from the command line after activating your virtualenv (see the "Usage" section here).
  
• In order to get the pweave command to run with my virtualenv, I manually edited the shebang in /usr/local/bin/pweave to directly point to the Python binary in my virtualenv: #!/Users/max/.virtualenvs/data/bin/python