A User’s Guide to this Book

Running Code

The code chunks throughout the book are executed in one of several ways. The most basic way that these chunks are executed is using the Mume markdown processor. The syntax used to pass parameters for code chunks is specific to Mume. As it processes the markdown into html, it identifies the code chunks, executes them, and puts the output directly into the output.

The examples in the book can be executed directly inline with the right editor and plugins. You will need to use the Markdown Preview Enhanced plugin for either Atom or Visual Studio Code. This wonderful plugin allows for realtime preview and instant code execution right in the editor.

I recommend changing the settings to not break on single newlines. I try to stick to the one-sentence-per-line policy to ease the process of reviewing git diffs.

Making Improvements

All of the source for this book is available on github. As a result, you can contribute improvements of your own. A project of this scale always has bugs. If you find a bug, you can fork the repository, fix the bug, and make a pull request.

There are a couple things to keep mind:

  • Any code generated in the ds2/ directory is scraped from the text in the prose folder. Edit the markdown file, not the .py file.

  • Similarly, the fullbook* files in the docs/ directory are generated by the build. These files should also not be edited.

  • Please avoid hard-wrapping lines. I guess some people still do this.

Building the book

Currently you will not be able to build to book yourself unless you comment out the code blocks that generate figures. The figure generation currently depends on some as-yet unreleased libraries.

Without those blocks, the build depends on prosecode. You can pip install prosecode and then use the make targets in the project’s Makefile.