WIXLIB

D2L-Book: A Toolkit for Hands-onBooksRelease 0.1.17Mu LiJan 12, 2022

Contents1Installation2User Guide2.1 Creating Your Project . . . . .2.2 Editing Source Files . . . . .2.3 Building . . . . . . . . . . . .2.4 Deploying . . . . . . . . . . .2.5 Markdown Cells . . . . . . .2.6 Code Cells . . . . . . . . . .2.7 Group Code Blocks into Tabs2.8 Creating Slides . . . . . . . .2.9 Colab . . . . . . . . . . . . .33.552021274449515153Development Guide553.1 Build pipeline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55Bibliography57i

ii

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 Learning1 for a book example and AutoGluon2for a package document site example.The 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. Oryour package documents have multiple tutorials to walk readers through your package usage throughexamples. These codes should be runnable and maintainable. You would like to publish both a HTML website and a printable PDF version. You expect the websiteshould be modern, searchable and mobile friendly, and the PDF version should be at the same quality aswritten using LaTeX.To achieve the above goals, d2lbook combines Jupyter Notebook3 , the widely used interactive environmentin Python, and Sphinx4 , the de facto document building system for Python packages. In particular, its mainfeatures include: Using markdown5 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 evaluatethe 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.If d2lbook does not fit your requirements, you may check the following tools: Jupyter book6 : very similar to d2lbook for publishing Jupyter notebooks. Two main design differencesare 1) d2lbook encourage you to use markdown file format and remove all code outputs before savingnotebooks. 2) d2lbook uses 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 Pythoncodes. gitbook7 : very convenient to push a book written with markdown if you don’t need to run them as Jupyternotebooks. sphinx-gallery8 , a Sphinx plugin to evaluate and publish your tutorials. It requires you to know how touse Sphinx and write your tutorials in .py format with the rst index.htmlContents1

2Contents

1 InstallationThe d2lbook package is tested under macOS and Linux. (You are welcome to contribute a Windows release).First make sure you have pip9 available. In option, we recommend conda10 for libraries that pip doesn’tsupport.Now install the command-line interface.pip install git https://github.com/d2l-ai/d2l-bookThis is a d2lbook pip package11 , but we recommend you to install latest version at Github directly since it’sunder fast developing.To build HTML results, we need pandoc12 . You can install it through conda install pandoc.Building the PDF version requires LibRsvg13 to convert your SVG images (our recommend format), e.g.conda install librsvg, and of course, you need to have a LaTeX distribution, e.g. Tex Live14 .tug.org/texlive/3

4Chapter 1. Installation

2 User GuideIn this part, we will cover1. How to create a project2. How to build and deploy the documents3. Various configuration options4. Markdown and code examples2.1 Creating Your ProjectLet’s start with a simple project from scratch.2.1.1 Project From ScratchFirst make a folder for our project.!mkdir -p mybookThen create two pages. The index.md is the index page which contains the table of contents (TOC), whichincludes the other page get started.md. Note that the TOC is defined in a code block with tag toc. Ifyou are familiar with Sphinx, you can find it’s similar to the TOC definition in Sphinx. Please refer to Section2.5 for more extensions d2lbook added to markdown. Also note we used the build-in magic writefileto save a code block into file provided by Jupyter15 .%%writefile mybook/index.md# My BookThe starting page of my book with d2lbook . tocget started Writing /stable/interactive/magics.html5

%%writefile mybook/get started.md# Getting StartedPlease first install my favorite package numpy .Writing mybook/get started.mdNow let’s build the HTML version.!cd mybook && d2lbook build html[d2lbook:build.py:L143] INFO2 notebooks are outdated[d2lbook:build.py:L145] INFO[1] ./index.md[d2lbook:build.py:L145] INFO[2] ./get started.md[d2lbook:build.py:L149] INFOEvaluating notebooks in parallel with 4 CPU , workers and 4 GPU workers[d2lbook:resource.py:L196] INFOStarting task "Evaluating ./index.md" on , CPU [1][d2lbook:resource.py:L159] INFOStatus: 1 running tasks, 0 done, 1 not , started[d2lbook:resource.py:L164] INFO- Task "Evaluating ./index.md" on CPU , [1] is running for 00:00:00[d2lbook:execute.py:L404] INFOExecuting notebook with kernel: python[d2lbook:resource.py:L223] INFOTask "Evaluating ./index.md" on CPU [1] is , finished in 00:00:02[d2lbook:resource.py:L196] INFOStarting task "Evaluating ./get started.md" , on CPU [1][d2lbook:resource.py:L159] INFOStatus: 1 running tasks, 1 done, 0 not , started[d2lbook:resource.py:L164] INFO- Task "Evaluating ./get started.md" on , CPU [1] is running for 00:00:00[d2lbook:execute.py:L404] INFOExecuting notebook with kernel: python[d2lbook:resource.py:L223] INFOTask "Evaluating ./get started.md" on CPU , [1] is finished in 00:00:02[d2lbook:resource.py:L142] INFOAll 2 tasks are done, sorting by runtime:[d2lbook:resource.py:L148] INFO- 00:00:02 on CPU [1] for Evaluating ./, index.md[d2lbook:resource.py:L148] INFO- 00:00:02 on CPU [1] for Evaluating ./, get started.md[d2lbook:build.py:L53] INFO Finished "d2lbook build eval" in 00:00:18[d2lbook:build.py:L287] INFO2 rst files are outdated[d2lbook:build.py:L289] INFOConvert build/eval/index.ipynb to build/rst/, index.rstConvert build/eval/get started.ipynb to[d2lbook:build.py:L289] INFO, build/rst/get started.rst[d2lbook:build.py:L53] INFO Finished "d2lbook build rst" in 00:00:18[d2lbook:build.py:L53] INFO Finished "d2lbook build ipynb" in 00:00:00[d2lbook:build.py:L53] INFO Finished "d2lbook build colab" in 00:00:00[d2lbook:build.py:L53] INFO Finished "d2lbook build sagemaker" in , 00:00:00Running Sphinx v4.3.2making output directory. donebuilding [mo]: targets for 0 po files that are out of datebuilding [html]: targets for 2 source files that are out of date(continues on next page)6Chapter 2. User Guide

(continued from previous page)updating environment: [new config] 2 added, 0 changed, 0 removedlooking for now-outdated files. none foundpickling environment. donechecking consistency. donepreparing documents. donewaiting for workers.generating indices. genindex donewriting additional pages. search donecopying static files. donecopying extra files. donedumping search index in English (code: en). donedumping object inventory. donebuild succeeded.The HTML pages are in build/html.[d2lbook:build.py:L53] INFO Finished "d2lbook build html" in 00:00:19The HTML index page is then available at mybook/ build/html/index.html.2.1.2 ConfigurationYou can customize how results are built and published through config.ini on the root folder.%%writefile mybook/config.ini[project]# Specify the PDF filename to mybook.pdfname mybook# Specify the authors names in PDFauthor Adam Smith, Alex Li[html]# Add two links on the navbar. A link consists of three# items: name, URL, and a fontawesome icon. Items are separated by commas.header links PDF, https://book.d2l.ai/d2l-book.pdf, fas fa-file-pdf,Github, https://github.com/d2l-ai/d2l-book, fab fa-githubWriting mybook/config.iniLet’s clear and build again.!cd mybook && rm -rf build && d2lbook build html[d2lbook:config.py:L12] INFO[d2lbook:build.py:L143] INFO[d2lbook:build.py:L145] INFO[d2lbook:build.py:L145] INFO[d2lbook:build.py:L149] INFO, workers and 4 GPU workersLoad configure from config.ini2 notebooks are outdated[1] ./get started.md[2] ./index.mdEvaluating notebooks in parallel with 4 CPU (continues on next page)2.1. Creating Your Project7

(continued from previous page)[d2lbook:resource.py:L196] INFOStarting task "Evaluating ./get started.md" , on CPU [3][d2lbook:resource.py:L159] INFOStatus: 1 running tasks, 0 done, 1 not , started[d2lbook:resource.py:L164] INFO- Task "Evaluating ./get started.md" on , CPU [3] is running for 00:00:00[d2lbook:execute.py:L404] INFOExecuting notebook with kernel: python[d2lbook:resource.py:L196] INFOStarting task "Evaluating ./index.md" on , CPU [1][d2lbook:resource.py:L159] INFOStatus: 2 running tasks, 0 done, 0 not , started[d2lbook:resource.py:L164] INFO- Task "Evaluating ./get started.md" on , CPU [3] is running for 00:00:02[d2lbook:resource.py:L164] INFO- Task "Evaluating ./index.md" on CPU , [1] is running for 00:00:00[d2lbook:resource.py:L223] INFOTask "Evaluating ./get started.md" on CPU , [3] is finished in 00:00:03[d2lbook:execute.py:L404] INFOExecuting notebook with kernel: python[d2lbook:resource.py:L223] INFOTask "Evaluating ./index.md" on CPU [1] is , finished in 00:00:02[d2lbook:resource.py:L142] INFOAll 2 tasks are done, sorting by runtime:[d2lbook:resource.py:L148] INFO- 00:00:02 on CPU [1] for Evaluating ./, index.md- 00:00:03 on CPU [3] for Evaluating ./[d2lbook:resource.py:L148] INFO, get started.md[d2lbook:build.py:L53] INFO Finished "d2lbook build eval" in 00:00:05[d2lbook:build.py:L287] INFO2 rst files are outdatedConvert build/eval/index.ipynb to build/rst/[d2lbook:build.py:L289] INFO, index.rst[d2lbook:build.py:L289] INFOConvert build/eval/get started.ipynb to, build/rst/get started.rst[d2lbook:build.py:L53] INFO Finished "d2lbook build rst" in 00:00:06[d2lbook:build.py:L53] INFO Finished "d2lbook build ipynb" in 00:00:00[d2lbook:build.py:L53] INFO Finished "d2lbook build colab" in 00:00:00[d2lbook:build.py:L53] INFO Finished "d2lbook build sagemaker" in , 00:00:00Running Sphinx v4.3.2making output directory. donebuilding [mo]: targets for 0 po files that are out of datebuilding [html]: targets for 2 source files that are out of dateupdating environment: [new config] 2 added, 0 changed, 0 removedlooking for now-outdated files. none foundpickling environment. donechecking consistency. donepreparing documents. donewaiting for workers.generating indices. genindex donewriting additional pages. search donecopying static files. donecopying extra files. donedumping search index in English (code: en). donedumping object inventory. donebuild succeeded.(continues on next page)8Chapter 2. User Guide