DocOnce cheat sheet

We considered using DocOnce, a package originally developed by Hans Petter Langtangen. This is not currently being used for this project, but here are some notes that may be useful to others...

Installation

git clone https://github.com/hplgit/doconce.git
cd doconce
pip install .

Basic usage

Make a file called filename.do

Start with block like

TITLE: X
AUTHOR: Y
DATE: today

Generate notebook:

doconce format ipynb myfile

Generate pdf:

doconce format pdflatex myfile --latex_code_style=lst
pdflatex myfile

##Markup

Code: put it in blocks like

!bc pycod
import math
!ec

Math: works just fine with $ and $$. For other environments, probably need to use

!bt
x=y
!et

Headings: use === on both sides.

Links: Markdown-style links work fine for notebooks, because they just get inserted as-is to the notebook, which interprets them correctly. But that won't work for converting with doconce to other formats; see http://hplgit.github.io/doconce/doc/pub/quickref/quickref.html and scroll down to "Hyperlinks".

Editing the Doconce file while running code in the notebook

It's a bit of a hassle to use Doconce with code that you are still developing and debugging in the notebook. It would be ideal to have the interactive code experience of the notebook combined with the readable Doconce text file. The best setup I have so far goes like this:

Create a shell script run_do.sh with the following contents:

#!/bin/bash
doconce format ipynb *.do

Then on Mac OS X use fswatch (brew install fswatch):

fswatch /my/directory/*.do | xargs -n1 /path/to/run_do.sh

Now, whenever a .do file changes, the corresponding IPython notebook is automatically regenerated. This means, of course, that changes made in the notebook will get overwritten. Also, you have to reload the browser page to get the updated notebook, which makes it quite clunky.

On other *nix OSes, you can use inotifywatch in place of fswatch.

What would be ideal: 2-way lossless conversion between .ipynb and .do formats. HPL has made this closer to a reality: https://github.com/hplgit/doconce/issues/29.

##Caveats

%matplotlib inline is automatically put at the top of cells where you import matplotlib. I don't know how to break text in to multiple cells if there is no code in between.

No automatic solution for getting the output (figures, etc.) that the notebook would generate into the doconce file?

Converting to Latex and then trying to run pdflatex gave me tons of errors.