文档总体
一般来说，一个编写良好且维护良好的文档可以分为4个具体的元素，如本文档所述：
- 参考资料
- 讨论
- 教程
- 如何使用指南
在我们的情况下，通过docstrings和Sphinx从它们生成html内容来实现1。我们已经有一个强大的基础参考资料，许多人正在努力增加覆盖范围(包括我自己)。
关于2,我们已经在GitHub问题和Pull Request页面上使用了gitter、邮件列表和特定问题的讨论。我们在3和4之间有一些重叠，因为我们既使用Jupyter笔记本进行教程，也使用它们进行指南。但是，这并不十分清楚哪个笔记本是教程还是指南。例如，我认为sklearn_api笔记本是教程，因为它们只展示基础知识(手把手教用户),而像word2vec IMDB/Wikipedia这样的模型特定笔记本更像是指南，因为它们解决了非常具体的问题。也许我们需要将它们分成两个类别(文件夹)名为tutorials和guides。
问题
非常重要的是，教程始终要运行(新版本不会破坏笔记本),并且在任何地方都要运行(教程将在每个操作系统、Python版本或发行版等处运行)。目前，这是很难保证的。
解决方案
我们需要测试这些笔记本。我所说的测试是指确保所有单元格都能运行且不引发任何错误。(我们是否也可以测试精确的输出？)
大多数谷歌搜索结果显示了不好的解决方案，但这两个似乎有希望(尽管有点hacky):
- https://gist.github.com/lheagy/f216db7220713329eb3fc1c2cd3c7826
- https://blog.thedataincubator.com/2016/06/testing-jupyter-notebooks/
优点 - 可能比其他方法的工作量少
- 没有额外的依赖项
缺点 - 对我来说似乎有点hacky(@menshikh-iv的想法？)
- 这些测试将确保没有引发错误，但对结果的正确性一无所知。我们可以在笔记本中放置Assert以确保它们被引发，但这会使笔记本看起来很丑陋。
- 笔记本不会自动转换为
rst,因此我们最终需要处理两个“真实来源”：官方doc page和笔记本本身。
替代方案
正如我们与@menshikh-iv讨论的那样，也许我们应该从笔记本迁移到Sphinx gallery。采用这种方法，我们的教程将是Python脚本。
优点
- 教程是python文件而不是.ipynb文件。
- 我们可以直接生成文档
rst。这确保了有一个单一的真实来源，新的笔记本可以轻松地添加到在线文档中。
缺点 - 需要与绘图相关的新依赖项，因为这主要是个绘图框架。
- 实现起来需要更多的时间，因为我需要熟悉它。
- 就我而言，还不太清楚我们将如何对其进行测试。
额外思考
我们是否还可以在教程中添加可视化？使用这两种替代方案都很容易，但我不确定我们能否提出有意义的图表。
3条答案
按热度按时间gojuced71#
感谢发布@steremma 👍
大家好，@yurkai@anotherbugmaster@CLearERR 让我们讨论当前的观点！
km0tfn4u2#
关于2:我们几乎忽略了堆栈溢出，这看起来不是一个好主意(因为这是一个非常受欢迎的QA服务，比我们的邮件列表更受欢迎得多)
关于3, 4(总体观点):我们没有将其拆分，我们有许多笔记本，其中包含：
它都放在一个堆中，很难找到你需要的东西。我们没有任何类型的“索引”。
关于由@steremma提出的“测试”-我已经尝试了这些解决方案，但这不起作用，因为
此外，笔记本还会产生许多问题，如
出于这个原因，@anotherbugmaster和我提议https://github.com/sphinx-gallery/sphinx-gallery方法用于“教程”和“如何使用”指南(而不是笔记本)。但是在这种情况下，当我们的笔记本演示大型(在数据大小/运行时间/消耗内存方面的意义)端到端示例时，我们可以创建一个新的仓库(仅用于笔记本),并将其移动到此仓库。
此外，作为“免费”福利，我们收到了以下优点：
.rst和.ipynb,它们完全不同步，因为贡献者只修改.ipynb)关于由@steremma提到的这种方法的缺点：
需要与绘图相关的新依赖项，因为这主要是个绘图框架。
这不是一个问题，因为目前只依赖于文档(而不是“核心”依赖项)。
由于我需要熟悉它，所以实现起来需要更多的时间。
这并不难，实际上@anotherbugmaster已经制作了一些示例，说明如何在#1809中使用它。
对我来说，并不是完全清楚我们将如何进行测试。
当您构建文档时，只需运行所有这些“画廊”示例(这是CLI的一个选项)。
vhipe2zx3#
我同意提出的观点，尤其是在跟踪笔记本方面遇到的困难，因为我在工作场所也遇到了同样的问题。与
sphinx gallery相关的PR将是与它一起工作的有用参考。我将在完成之前分配的任务后(可能从现在起的一周内)开始研究它。