D2L-Book: A Toolkit for Hands-on Books¶
The D2L Book (
d2lbook) package helps you build and publish a book
with Python codes, or Python package documents with tutorials. You
can check Dive into Deep Learning for a book
example and AutoGluon for a package
document site example.
d2lbook is designed to meet the following two requirements:
Your book may contain a large amount of Python codes and you expect your readers to run them. Or your package documents have multiple tutorials to walk readers through your package usage through examples. These codes should be runnable and maintainable.
You would like to publish both a HTML website and a printable PDF version. You expect the website should be modern, searchable and mobile friendly, and the PDF version should be at the same quality as written using LaTeX.
To achieve the above goals,
d2lbook combines Jupyter
Notebook, the widely used interactive
environment in Python, and
Sphinx, the de facto document
building system for Python packages. In particular, its main features
Using markdown for your contents.
A minimal configuration file to customize the building so you can focus on the contents.
Evaluating all codes to obtain their output before publishing to validate the correctness. We only evaluate the updated codes to save cost.
Being able to reference sections, figure, tables, equations, function, and class.
Pipelines to publish your website through Github or AWS.
d2lbook does not fit your requirements, you may check the
Jupyter book: very similar to
d2lbookfor publishing Jupyter notebooks. Two main design differences are 1)
d2lbookencourage you to use markdown file format and remove all code outputs before saving notebooks. 2)
d2lbookuses Sphinx instead of Jekyll adopted by Jupyter book to build the document. Jekyll is easier to customize the theme, while Sphinx has better supports for PDF and analyzing Python codes.
gitbook: very convenient to push a book written with markdown if you don’t need to run them as Jupyter notebooks.
sphinx-gallery, a Sphinx plugin to evaluate and publish your tutorials. It requires you to know how to use Sphinx and write your tutorials in
.pyformat with the