imclab / reporter

Literate data analysis with iPython notebooks and Jekyll.

Reporter

Reporter is a framework for publishing "literate data analysis." Crudely, it's a fancy HTML template with a toggle button for showing/hiding code and other inputs. Less crudely, it tries to resolve the tension, or bridge the gap, between showing your work and communicating with non-technical readers. To learn more, see a live example or longer explanation. To get started, read on.

Installation

Reporter is built on the Ruby-based Jekyll static-site generator and accepts IPython notebooks as "posts." Support for other inputs, such as knitr and Literate Python files, is planned.

To run Reporter, clone this repository onto your computer:

git clone https://github.com/jsvine/reporter

And then install the required Ruby gems:

gem install jekyll kramdown sanitize crochet

... or:

bundle install

Usage

Create a _posts/ directory inside the directory where this README exists. Place the IPython notebooks (.ipynb files) you want inside that directory, just like you would do for Markdown files in a standard Jekyll project. (You can still put Markdown files in the directory; they'll get processed as usual.)

Rather than use YAML front-matter, Reporter looks for posts variables in .ipynb files' metadata object, which is automatically present at the top of every such file. (.ipynb files are, in fact, just specalized JSON objects.) But Reporter makes sure that you don't need to set any, that you can use IPython notebooks without any modifications. For instance, you don't need to a specific date variable for notebooks, either in the file path or the metadata, though you can if you'd like to. The mtime plugin sets posts' dates, where not specified, to the last time the file was modified.

Other than that, you run Reporter just like you would any other Jekyll project: jekyll build to generate the site, jekyll serve to build the site and preview it on localhost.

You can change the site title, intro, and footer in _config.yml.

Future Plans

• Support for more input formats:

  • knitr
  • Literate Python
  • Others?

• Support for versioning.

License

Reporter is licensed under the MIT License. See LICENSE.txt for more details.

Contributing

1. Fork it
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create new Pull Reques