1

I have a Python jupyter notebook, which I can successfully export to HTML with a table of content through the command line:

$ jupyter nbconvert nb.ipynb --template toc2

How do I do the same, but programmatically (via API)?

This is what I achieved so far: 

import os
import nbformat
from nbconvert import HTMLExporter
from nbconvert.preprocessors import ExecutePreprocessor

nb_path = './nb.ipynb'
with open(nb_path) as f:
    nb = nbformat.read(f, as_version=4)

ep = ExecutePreprocessor(kernel_name='python3')
ep.preprocess(nb)
exporter = HTMLExporter()
html, _ = exporter.from_notebook_node(nb)

output_html_file = f"./nb.html"
with open(output_html_file, "w") as f:
    f.write(html)
    f.close()
print(f"Result HTML file: {output_html_file}")

It does successfully export the HTML; however without the table of content. I don't know how to set the --template toc2 through the API.

Bruno Ambrozio
  • 402
  • 3
  • 18

2 Answers2

2

I found two ways to do this:

The way that most faithfully reproduces $ jupyter nbconvert nb.ipynb --template toc2 involves setting the HTMLExporter().template_file attribute with the toc2.tpl template file.

  • The main trick is to find where this file lives on your system. For me it was <base filepath>/Anaconda3/Lib/site-packages/jupyter_contrib_nbextensions/templates/toc2.tpl
  • Full code below:
from nbconvert import HTMLExporter
from nbconvert.writers import FilesWriter
import nbformat
from pathlib import Path

input_notebook = "My_notebook.ipynb"
output_html ="My_notebook"
toc2_tpl_path = "<base filepath>/Anaconda3/Lib/site-packages/jupyter_contrib_nbextensions/templates/toc2.tpl"

notebook_node = nbformat.read(input_notebook, as_version=4)

exporter = HTMLExporter()
exporter.template_file = toc2_tpl_path # THIS IS THE CRITICAL LINE

(body, resources) = exporter.from_notebook_node(notebook_node)

write_file = FilesWriter()
write_file.write(
    output=body,
    resources=resources,
    notebook_name=output_html
)

An alternative approach is to use the TocExporter class in the nbconvert_support module, instead of HTMLExporter.

  • However, this mimics the command line expression jupyter nbconvert --to html_toc nb.ipynb rather than instead setting the template of the standard HTML export method
  • The main issue with this approach is that there does not seem to be a way to embed figures with this method, which is the default for the template-based method above
  • However, if figure embedding doesn't matter, this solution is more flexible across different systems since you don't have to track down different file paths for toc2.tpl
  • Here is an example below:
from nbconvert import HTMLExporter
from nbconvert.writers import FilesWriter
import nbformat
from pathlib import Path
from jupyter_contrib_nbextensions.nbconvert_support import TocExporter # CRITICAL MODULE

input_notebook = "My_notebook.ipynb"
output_html ="My_notebook"

notebook_node = nbformat.read(input_notebook, as_version=4)

exporter = TocExporter() # CRITICAL LINE

(body, resources) = exporter.from_notebook_node(notebook_node)

write_file = FilesWriter()
write_file.write(
    output=body,
    resources=resources,
    notebook_name=output_html
)

As a final note, I wanted to mention my motivation for doing this to anyone else who comes across this answer. One of the machines I work on uses Windows, so to get the command prompt to run jupyter commands requires some messing with the Windows PATH environment, which was turning in to a headache. I could get around this by using the Anaconda prompt, but this requires opening up the prompt and typing in the full command every time. I could try to write a script with os.system(), but this calls the default command line (Windows command prompt) not the Anaconda prompt. The methods above allow me to convert Jupyter notebooks to HTML with TOCs and embedded figures by running a simple python script from within any notebook.

bds
  • 51
  • 4
0

This was not clear in the documentation, but the constructor of the TemplateExporter class mentions the folowing:

template_file : str (optional, kw arg)
Template to use when exporting.

After testing it, I can confirm the all you need to do is add the filepath to the template file under this argument for you exporter.

HTMLExporter(template_file=path_to_template_file)
TimeTerror
  • 546
  • 5
  • 5