Introduction to Jupyter Books — Part 1
A guide to publishing your own production quality Technical book
Project Jupyter has been a boon for the Data Science, Machine Learning, and AI Community of Practitioners and Developers.
Every time I start building a Report or a Model, the first tool that comes to my mind is
“The Legendary Jupyter Notebook”
I’ve also worked with Jupyter Lab, an easily accessible collection of Jupyter Notebooks and other files. In February 2019, Project Jupyter further launched Jupyter Books — a complete package with amazing capabilities.
Before getting started, I would like to mention the fact that building the best Jupyter Books would require some basic HTML understanding, in fact as long as you can use basic logic and figure out a way to edit stuff inside your HTML files, you’re good to go. Let’s hit it!
First, what can you do with Jupyter Books?
- Publish Technical Content in Jupyter Notebooks including rich syntaxes such as citations, cross-references, and numbered equations
- Quality Documentation with MathJax, Markedly Structured Text (MyST), and PDF’s
- Interactive Outputs and links to Project repositories and Issues on Github
- Customized Rendering for Notebooks, Images, and Figures with Sphinx
Most importantly, you are now capable of publishing your own production quality Technical Data Science Book Online, with Code, Images and Documents.
Let’s get started with Jupyter Books
Since, Jupyter books are comparatively new and still in a rapid development phase, to keep your other installations and dependencies safe, it’s recommended to first set up your Virtual Environment
Virtual Environment
conda create -n JBook python=3.6conda activate JBook # Deactivate once done : conda deactivate
Installation
pip install jupyter-bookCreate your first Jupyter Book : Source files for the Book
jupyter-book create MyFirstJupyterBook
Build your Jupyter Book : Runs the Book over source files
jupyter-book build MyFirstJupyterBook/
and just like that, you’ve built a Jupyter Book. Let’s make it yours now.
What Now?
If you followed along, this is what you should get when you open the MyFirstJupyterBook/_build/html/index.html file in your browser
Personalize !
- Change the Image of the book
- The Description
- Add Github Repository Link
- Add a Jupyter Notebook
The 2 important files to personalize a JupyterBook —
- _config.yml: To manage the Book Design Settings
- _toc.yml: To define the Table of Contents
Let’s look at each one of them individually
_config.yml
Customizable options —
- title: The Title of the Book
- author: Yours Truly
- logo: You!
- Github URL
We start with copying an image from our Local desktop to the Jupyter Book Directory with the following command :
cp Desktop/<IMG>.<EXT> MyFirstJupyterBook/
Example : cp Desktop/DP.jpg MyFirstJupyterBook/Open the file with vim editor, hit ‘i’ Insert, Edit & Save with “Esc”+ “:wq”
vim _config.yml
After editing the _config.yml file, go back to the parent folder and build the Book again to implement the changes made, TA-DA !!
Further, edit the “intro.md” file to change the Introduction Statements to your Book.
Finally, let’s add a Jupyter Notebook to our Book
Build a simple Jupyter Notebook using Anaconda and add a few markdown cells and Code Cells to make sure there is some content in the notebook
Copy the Jupyter Notebook from your current directory to your Jupyter Book
cp Downloads/My_Jupyter_Notebook.ipynb ./MyFirstJupyterBookAdd this Jupyter Notebook to your Table of Contents in the _toc.yml file and edit as follows -
Build your Jupyter Book one last time and the magic happens!
In the “Content in Jupyter Notebook” Section, you will find the first Markdown of your Notebook as a file and BINGO!
Congratulations! on building your first Jupyter Book and I hope you enjoyed the process with minimum complications. To be honest, we just scratched the surface and there’s a lot more to be achieved with this super Tool. Part — 2 Coming Soon…
Have a great day! Cheers!
