Turning this into a book

[leouieda]

We (me and @birocoles) have plans of turning this into a book. The general idea is to have a short, direct, example driven book. This means adding lots of code to the current text we have.

We also want to make the text and code freely available on the internet (probably under a Creative Commons license). [Recommended read: Textbook Manifesto]

Some options for writing the actual book:

1. Use Jupyter notebooks for everything.

   Advantages:

   • The text and code will be together and the reader can execute the code without copy pasting.
   • Can easily insert images and interactive widgets
   • Can execute online (no installing necessary) on http://mybinder.org/
   • Can export notebooks to PDF and HTML with a bit of effort using jupyter nbconvert

   Disadvantages:

   • No referencing support (no Bibtex or Latex \cite commands)
   • No numbering of equations
   • No good way of testing the output of the code (like doctests)
   • Terrible diff/merge so not good for developing using Github PRs.

2. Use Latex for the text and notebooks for the code

   Advantages:

   • All the benefits of writing in Latex
   • Executing code still in notebook form
   • Can use PRs to develop the text

   Disadvantages:

   • Bad export of text to HTML
   • Separate text with theory from the code and results
   • Might have to copy/repeat text from the book in the notebooks to make them understandable (or vice-versa)
   • Still bad PR workflow for code

3. Use Sphinx with some useful plugins:

   Advantages:

   • It's the default documentation generation system for Python projects (including Fatiando). So there are a lot of plugins and people are familiar with it.
   • Can generate PDF, HTML and EPUB from the same source
   • Writing in reStructuredText (.rst) and .py files is PR friendly
   • Access to (numbered) Latex equations and hyperreferences
   • Bibtex citations using sphinx natbib
   • Test code in the book using doctest syntax
   • Code that produces matplotlib plots
   • Sections with notebook-style text + code + images using sphinx-gallery (it also automatically generates a .ipynb file from the input .py or .rst)

   Disadvantages:

   • Would have to write sections with code in .py files (no interactivity during the development)
   • Can't use some rich-text Jupyter notebook features (widgets, embded videos, etc)
   • Would probably need to hack some plugins to do everything we want. But this can be done only when needed.
   • Will need to test if all the plugins above work well together (particularly sphinx-gallery and sphinx-natbib).

My thoughts: I tend toward using Sphinx. Support for a PR friendly workflow is a must if we are to write this together. Also, through some plugins we can get most of the advantages of notebooks. The code can be automatically tested on TravisCI. The generated notebook files can be automatically commited to a separate repository and used online with mybinder.

[rowanc1]

This is a fantastic articulation of some of the challenges and ways forward for writing a computational-enabled book. Lots of progress over the last several years, but many of these are still issues - especially when doing more writing/reviewing than coding.