Convert Notebooks to PDFs using Sphinx

Hello, in this short article I will be discussing how we can convert jupyter-notebook files into a pdf. Generally, this procedure is very important when we need to create documentation like a book or a course material. I will be implementing the steps in Linux (Ubuntu to be specific). It will be indifferent in Windows however, some extra libraries may be required during installation. So, let’s get started.

Step 1: Installing the necessary libraries and applications from the original documentation here. From this link, follow all the procedures line by line and install all the necessary libraries.

Step 2: Now, create a directory and install sphinx files in it. You can follow the following procedure:

a. Create Directory: We are creating a directory name `pdf_conversion` on the Documents as:

• mkdir ~/Documents/pdf_conversion

b. Navigate to the created Directory: We can do this as:

• cd ~/Documents/pdf_conversion

Step 3: Now, start the Sphinx quickstart as:

• python -m sphinx.cmd.quickstart

Then, do as performed here:

We are going to create a separate source and build directories. This will be easy for us to segregate the notebook files and the output pdf files.

Now,

We are working on the Future Sales Prediction project notebook so my project name is `Future Sales Prediction`here. Then, I have written my name as author and fixed the project release date to 2021. With this enough information, you can just advance to other asked questions by pressing the Enter key.

Step 4: Add extensions on source/conf.py. The conf.py initially has no extensions and appears as:

For conversion of a notebook with latex and math contents, we should add these two extensions:

extensions = [
“nbsphinx”,
“sphinx.ext.mathjax”,
]

(Optional)Step 5: Removing irregular blank pages in pdf converted from notebook file. The pdf file converted from notebook has lot of intentionally left blank spaces in default mode. So, some extra coding steps need to be implemented to avoid those blank spaces. For avoiding these blank spaces, we could add the following code in source/conf.py.

latex_elements = {
“classoptions”: “,openany,oneside”,
}

The implementations from step 4 and step 5 appear as:

Step 6: Adding up the notebook file for conversion. In this step, we copy the notebook file that we wish to convert into a pdf inside the source folder.

Initially, our folder and file structure is:

Now, after adding up the notebook file in the source folder for conversion, we have our directory structure as:

Here, you can see that we have added a future_sales_prediction.ipynb notebook here in the source directory.

Step 7: Editing the source/index.rst. The index.rst file inside the source folder is responsible for creating the table of contents. Here, in this index.rst file, we clear all the contents under the caption: Contents: And, then we add our notebook file name as follows:

Here, you can see that we have added the exact name of the file as in the notebook. Now, with this, our conversion is ready to build.

Step 8: Building the notebook. Now, I will show you some terminal commands that will be used to build the notebook into a pdf.

• python -m sphinx source build -b latex

Here, we are doing a sphinx latex build from the original source directory into the build directory. We will see several output build files on this directory as well. Let’s see the build:

After performing the above command, you may reach here at:

So, as the sphinx is also suggesting, our final task will be to make the build. For this, we will perform the following command.

• make latexpdf

Remember, we may still receive several warnings. However, the proceeding is the best way because after we obtain the pdf file with `make latexpdf` command, we can check out the parts where the pdf has errors. It will be easier for us to find errors in that way.

Now, to check out your pdf file, you can just navigate to the build/latex and there is your pdf. If your notebook also consists some images, there you can find images from the notebook well. Several files like .tex, .cls etc are latex and document class files.

So, this is all for this short article. You will still face many issues like image importing error, latex $ spacing error, table of contents error, etc. We could discuss this in the next article.

Thank You!