在 Sphinx 文档中嵌入绘图图

Posted 2023-02-18

【中文标题】在 Sphinx 文档中嵌入绘图图

【英文标题】：Embed plotly graph in a Sphinx doc

【发布时间】：2018-02-26 09:41:07

【问题描述】：

我尝试使用 nbsphinx 嵌入一个包含绘图的 Jupyter 笔记本，但这些绘图没有显示在文档中，即使它们在 Jupyter 笔记本上看起来不错。

如何在 Sphinx documentation 中嵌入绘图图？我可以将它们包含为图像，但有更好的方法吗？有互动就好了！

我想做的是复制this page。它具有 Jupyter 笔记本风格的进出块，并显示使用 plotly 制作的交互式绘图。我该怎么做？

GitHub 问题提出here.

【问题讨论】：

这里有同样的问题。存在github.com/plotly/plotlyhtmlexporter。不确定如何从 nbsphinx 使用它。它还会弄乱我笔记本中的其他 HTML 单元格。

@phantomas1234 我已经用我提出的 GitHub 问题的链接更新了问题。试试那里的解决方案，看看它是否适合你。

使用 plotly 你可以输出带有output_type='div'的html。

使用新的FigureWidget 更容易。如果有兴趣，我可以准备一个答案。

【参考方案1】：

图表本身是 jupyter notebook 文件中的 HTML。 您可以在任何文本编辑器中打开 notebook.ipnb 文件，找到图形的 HTML 开始位置，将所有这些 html 复制到 html 文件中并保存，例如 a.html，然后在 RST doc 中插入原始 html。

.. raw:: 
    :file: a.html

【参考方案2】：

我可以看到两种解决方案，可以在 sphinx 文档中嵌入带有情节图形的笔记本单元格。

使用 nbconvert 或 nbsphinx 将笔记本转换为 html。请务必使用 notebook 渲染器以包含 plotly javascript 包（也许这就是您的数字未显示的原因）：有关 plotly 渲染器的文档，请参阅 https://plot.ly/python/renderers/。然后，您可以使用各种解决方案在您的 sphinx 文档中包含 html（请参阅Include standalone HTML page in sphinx document）。 使用 sphinx-gallery (https://sphinx-gallery.github.io/) 和它的情节刮板。使用 sphinx-gallery，您可以将文档页面编写为 python 脚本，该脚本由 sphinx 的 sphinx-gallery 扩展转换为 rest。要配置刮板，请参阅https://sphinx-gallery.github.io/advanced.html#integrate-custom-scrapers-with-sphinx-gallery。我们还有一个最小的存储库，展示了如何在https://github.com/plotly/plotly-sphinx-gallery 中一起使用 plotly 和 sphinx-gallery。 https://github.com/plotly/plotly-sphinx-gallery

【参考方案3】：

在 Python 中，您可以使用 plotly.tools.get_embed 函数生成 HTML 代码以嵌入 Plotly 图。

import plotly.tools as tls

tls.get_embed('https://plot.ly/~chris/1638')

【参考方案4】：

您可以将Jupyter Sphinx Extension 与 Plotly 的FigureWidget 结合使用：

... jupyter-execute::

   import plotly.graph_objects as go

   trace = go.Scatter(
       x=[0, 1, 2, 3, 4],
       y=[0, 1, 4, 9, 16],
   )
   layout = go.Layout(title='Growth')
   figure = go.Figure(data=[trace], layout=layout)

   go.FigureWidget(figure)

【讨论】：

这似乎不适用于我的 pdflatex...文档前面有一些 jupyter-execute 设置吗？

@MattRuge 我没有尝试过 LaTeX 输出，所以我不知道。 :-)

我通过让 jupyter-execute 转储 IMG 字节取得了一些进展，在乳胶 pdf 中显示为 png ``` .. jupyter-execute:: :hide-code: # Creates figure ## 为简洁而编辑 img_bytes = fig.to_image(format="png") Image(img_bytes) ``

我相信 plotly 默认不会生成静态图，除非您使用plotly.com/python/static-image-export 明确配置它。我目前正在寻找在 Github 存储库中具有交互式绘图图的 README.rst 文件，到目前为止，我已经设法使用静态图像。

【参考方案5】：

当 Sphinx 生成文档时，它没有描述 plotly 库，所以将以下行添加到您的 HTML 页面中：

<script src="https://cdn.plot.ly/plotly-latest.min.js"></script>

然后页面将再次活跃。