发布一个 python 包——你应该包括文档和测试吗？

Question

所以，我在 pypi 上发布了一个小型库，更多的是作为练习（“看看它是如何完成的”）而不是其他任何东西。

我已经在 readthedocs 上上传了文档，并且我的 git 存储库中有一个测试套件。

由于我认为任何可能对运行测试感兴趣的人都可能只是克隆 repo，并且该文档已经在线可用，因此我决定不在发布的包中包含 doc 和 test 目录，我只是想知道如果那是“正确”的事情。

我知道这个问题的答案是相当主观的，但我觉得这是一个很好的提问地方，以便了解社区认为什么是最佳做法。

Answer 1

这不是必需的，但建议在包中包含文档和单元测试。

关于文件：

老式或更好的说法是老式开源软件的源代码版本包含文档，这是（事实上？）标准（例如，看看 GNU 软件）。文档是代码的一部分，应该是发布的一部分，因为一旦你下载了源发布，你就独立了。您是否曾经在某处乘坐火车，需要快速查看模块 X 的文档但无法访问互联网的情况？然后您如释重负地意识到文档已经在本地了。

这方面的另一个重点是，您与代码捆绑在一起的文档肯定适用于代码版本。代码和文档是同步的。

还有一件事，特别是关于 Python：您可以使用 Sphinx 编写文档，然后在安装包的过程中根据文档源构建漂亮的 HTML 输出。我已经看到各种 Python 包正是这样做的。

关于测试：

想象一下，测试捆绑在源版本中，并且很容易由用户运行（您应该记录如何执行此操作）。然后，如果用户发现您的代码存在不易追踪的问题，他可以简单地在他的环境中运行单元测试，看看是否至少通过了这些测试。如果不是，那么您在指定代码的行为时可能做出了错误的假设，这很值得了解。我想说的是：如果你让用户执行单元测试变得非常简单，这对你作为开发人员来说是非常好的。