如何在 Sphinx 文档和 nbsphinx 中嵌入 Plotly 图表
[英]How to embed Plotly graphs in Sphinx documentation and nbsphinx
问题描述
I tried using nbsphinx to embed a Jupyter notebook containing plotly plots, but the plots don't show up in the documentation, even though they look fine on the Jupyter notebook.
我尝试使用nbsphinx嵌入一个包含 plotly 图的 Jupyter 笔记本，但这些图没有显示在文档中，即使它们在 Jupyter 笔记本上看起来不错。
How can I embed a plotly graph in Sphinx documentation ?如何在Sphinx文档中嵌入 plotly 图表？ I could include them as images, but is there a better way?我可以将它们包含为图像，但有更好的方法吗？ It'd be nice to have the interactivity!有互动就好了！
What I want to do is replicate this page .我想要做的是复制这个页面。 It has Jupyter notebook style in and out blocks, and it shows interactive plots made using plotly.它具有 Jupyter 笔记本风格的进出块，并显示使用 plotly 制作的交互式绘图。 How can I do that?我怎样才能做到这一点？
8 个解决方案
解决方案1
3 2019-08-13 20:44:46
The graph itself is an HTML inside jupyter notebook file.该图本身是 jupyter notebook 文件中的 HTML。 You can open notebook.ipnb file in any text editor, find where HTML of the graph starts, copy all this html into html file ans save it , say a.html, and then just insert raw html in RST doc.您可以在任何文本编辑器中打开 notebook.ipnb 文件，找到图形的 HTML 开始位置，将所有这些 html 复制到 html 文件中并保存，例如 a.html，然后在 RST doc 中插入原始 html。
.. raw::
:file: a.html
解决方案2
2 2019-07-26 09:21:50
I can see two solutions to embed your notebook cells with plotly figures in a sphinx documentation.我可以看到两种解决方案，在 sphinx 文档中嵌入带有情节图形的笔记本单元格。
- Convert the notebook to html using nbconvert or nbsphinx.使用 nbconvert 或 nbsphinx 将笔记本转换为 html。 Be sure to use the
notebookrenderer in order to include the plotly javascript bundle (maybe this was the reason why your figures did not display): see https://plot.ly/python/renderers/ for the documentation on plotly renderers.请务必使用notebook渲染器以包含 plotly javascript 包（也许这是您的数字未显示的原因）：有关 plotly 渲染器的文档，请参阅https://plot.ly/python/renderers/ 。 Then you can include the html in your sphinx doc with various solutions (see Include standalone HTML page in sphinx document ).然后，您可以使用各种解决方案在您的 sphinx 文档中包含 html（请参阅在 sphinx 文档中包含独立的 HTML 页面）。 - Use sphinx-gallery ( https://sphinx-gallery.github.io/ ) with its plotly scraper.使用 sphinx-gallery ( https://sphinx-gallery.github.io/ ) 和它的情节刮板。 With sphinx-gallery you write your doc page as a python script which is converted to rest by the sphinx-gallery extension of sphinx.使用 sphinx-gallery，您可以将 doc 页面编写为 python 脚本，该脚本由 sphinx 的 sphinx-gallery 扩展转换为 rest。 In order to configure the scraper see https://sphinx-gallery.github.io/advanced.html#integrate-custom-scrapers-with-sphinx-gallery .为了配置刮板，请参阅https://sphinx-gallery.github.io/advanced.html#integrate-custom-scrapers-with-sphinx-gallery 。 We have also a minimal repository showing how to use plotly and sphinx-gallery together in https://github.com/plotly/plotly-sphinx-gallery .我们还有一个最小的存储库，展示了如何在https://github.com/plotly/plotly-sphinx-gallery中一起使用 plotly 和 sphinx-gallery。 https://github.com/plotly/plotly-sphinx-gallery https://github.com/plotly/plotly-sphinx-gallery
解决方案3
0 2018-10-06 04:29:16
From Python, you can generate the HTML code to embed Plotly graphs with the plotly.tools.get_embed function.在 Python 中，您可以使用 plotly.tools.get_embed 函数生成 HTML 代码以嵌入 Plotly 图。
import plotly.tools as tls
tls.get_embed('https://plot.ly/~chris/1638')
解决方案4
0 2020-07-22 11:16:49
You can use the Jupyter Sphinx Extension :您可以使用Jupyter Sphinx 扩展：
.. 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)
figure.show()
解决方案5
0 2021-09-08 23:57:19
When Sphinx generate the document it doesn't describe the plotly library, so add the following line into your HTML page:当 Sphinx 生成文档时，它没有描述 plotly 库，所以将以下行添加到您的 HTML 页面中：
<script src="https://cdn.plot.ly/plotly-latest.min.js"></script>
then the page will be alive again.然后页面将再次活跃。
解决方案6
0 2022-06-17 09:52:25
We had this issue for both sphinx_rtd_theme and furo theme.我们对sphinx_rtd_theme和furo主题都有这个问题。 Because how Plotly and Sphinx themes using require.js , the default generated HTML output does not work within Sphinx context.因为 Plotly 和 Sphinx 主题如何使用require.js ，所以默认生成的 HTML 输出在 Sphinx 上下文中不起作用。 You get various loading errors with require.js or other files.使用 require.js 或其他文件时会出现各种加载错误。
Here is our solution:这是我们的解决方案：
- Make sure your JavaScript loads at
<head>in your theme.确保您的 JavaScript 在您的主题中加载到<head>。 If it loads at the end of the<body>no workaround is going to work.如果它在<body>末尾加载，则任何解决方法都不起作用。 - Server
require.jslocally from Sphinx_staticfolder从 Sphinx _static文件夹本地服务器require.js - Configure
requireby using custom.js使用 custom.js 配置require
Example conf.py :示例conf.py ：
html_js_files = [
"require.min.js", # Add to your _static
"custom.js",
]
Example custom.js:示例 custom.js：
requirejs.config({
paths: {
base: '/static/base',
plotly: 'https://cdn.plot.ly/plotly-2.12.1.min.js?noext',
},
});
This way这边走
- Notebook correctly renders interactive diagrams when running in Jupyter Notebook 在 Jupyter 中运行时正确呈现交互式图表
- Notebook correctly renders interactive diagrams when viewed as static HTML files Notebook 在作为静态 HTML 文件查看时正确呈现交互式图表
- Notebook correctly renders interactive diagrams when viewed on ReadTheDocs在 ReadTheDocs 上查看时，Notebook 正确呈现交互式图表
See the example open-source documentation here and the example notebook .请参阅此处的示例开源文档和示例笔记本。
解决方案7
0 2022-07-01 18:27:29
After trying many workarounds, the solution that worked for me was to add these lines at the beginning of the notebook.在尝试了许多解决方法之后，对我有用的解决方案是在笔记本的开头添加这些行。
import plotly plotly.offline.init_notebook_mode()
None of the solutions involving modifying the options nbsphinx_prolog , nbsphinx_requirejs_options and html_js_files in the conf.py , work for me.涉及修改 conf.py 中的选项nbsphinx_prolog 、 nbsphinx_requirejs_options和html_js_files的解决方案conf.py适合我。
I'm ussing the sphinx_rtd_theme html theme and the following versions:我正在使用sphinx_rtd_theme html 主题和以下版本：
nbsphinx==0.8.9
sphinx-autobuild==2021.3.14
sphinx==4.4.0
解决方案8
0 2022-08-30 18:28:55
Try this at the top of your notebook:在笔记本顶部试试这个：
import plotly.io as pio
pio.renderers.default = "sphinx_gallery"
This renderer makes sure your notebook (or cell output, or something, not sure.) includes the javascript resources that your cell output needs to render the plot.此渲染器确保您的笔记本（或单元格 output 或其他东西，不确定。）包含您的单元格 output 渲染绘图所需的 javascript 资源。
Other renderers, or settings, might achieve this as well.其他渲染器或设置也可能实现此目的。 But so far this is the only renderer I've tried where I can build notebooks with sphinx (jupyter book, actually), and the interactive plots show up in the build.但到目前为止，这是我尝试过的唯一一个可以使用 sphinx（实际上是 jupyter book）构建笔记本的渲染器，并且交互式绘图显示在构建中。
声明:本站的技术帖子网页，遵循CC BY-SA 4.0协议，如果您需要转载，请注明本站网址或者原文地址。任何问题请咨询:yoyou2525@163.com.