如何通过 nbconvert API 设置参数“--template toc2”？答案

【问题标题】：How to set the argument "--template toc2" through nbconvert API?如何通过 nbconvert API 设置参数“--template toc2”？
【发布时间】：2020-08-22 18:41:22
【问题描述】：

我有一个 Python jupyter notebook，可以通过命令行成功导出为 HTML with a table of content：

$ jupyter nbconvert nb.ipynb --template toc2

如何以编程方式（通过 API）做同样的事情？

这是我目前所取得的成就：

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}")

它确实成功地导出了 HTML；但是没有目录。我不知道如何通过API设置--template toc2。

【问题讨论】：

标签： python jupyter-notebook nbconvert jupyter-contrib-nbextensions

【解决方案1】：

我找到了两种方法：

最忠实地复制$ jupyter nbconvert nb.ipynb --template toc2 的方法是使用toc2.tpl 模板文件设置HTMLExporter().template_file 属性。

主要技巧是找到此文件在您的系统上的位置。对我来说是<base filepath>/Anaconda3/Lib/site-packages/jupyter_contrib_nbextensions/templates/toc2.tpl
完整代码如下：

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
)

另一种方法是在nbconvert_support 模块中使用TocExporter 类，而不是HTMLExporter。

但是，这模仿了命令行表达式 jupyter nbconvert --to html_toc nb.ipynb，而不是设置标准 HTML 导出方法的模板
这种方法的主要问题是似乎没有办法用这种方法嵌入图形，这是上面基于模板的方法的默认值
但是，如果图形嵌入无关紧要，则此解决方案在不同系统之间更加灵活，因为您不必跟踪 toc2.tpl 的不同文件路径
下面是一个示例：

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
)

作为最后一点，我想向遇到此答案的其他人提及我这样做的动机。我使用的其中一台机器使用 Windows，因此要让命令提示符运行 jupyter 命令需要对 Windows PATH 环境进行一些处理，这让我很头疼。我可以通过使用 Anaconda 提示符来解决这个问题，但这需要打开提示符并每次都输入完整的命令。我可以尝试使用os.system() 编写脚本，但这会调用默认命令行（Windows 命令提示符）而不是 Anaconda 提示符。上述方法允许我通过在任何笔记本中运行一个简单的 Python 脚本，将 Jupyter 笔记本转换为带有 TOC 和嵌入式图形的 HTML。

【讨论】：

【解决方案2】：

这在文档中并不清楚，但是TemplateExporter 类的构造函数提到了以下内容：

模板文件：str（可选，kw arg）
导出时使用的模板。

经过测试，我可以确认您需要做的就是在此参数下为您的导出器添加模板文件的文件路径。

HTMLExporter(template_file=path_to_template_file)

【讨论】：