因此，我在 pypi 上发布了一个小型库，更多的是作为练习（“看看它是如何完成的”）而不是其他任何东西。
我已经在 readthedocs 上上传了文档，并且我的 git repo 中有一个测试套件。
由于我认为任何可能对运行测试感兴趣的人都可能只是克隆存储库，并且该文档已经在线可用，因此我决定不在发布的包中包含 doc 和 test 目录，我只是想知道那是不是“正确”的事情要做。
我知道这个问题的答案是相当主观的，但我觉得这是一个很好的提问地方，以便了解社区认为什么是最佳实践。
问问题
360 次
1 回答
5
它不是必需的，但建议在包中包含文档和单元测试。
关于文档：
老式的或更好的说法是开源软件的老式源代码版本包含文档，这是（事实上？）标准（例如，看看 GNU 软件）。文档是代码的一部分，应该是发布的一部分，因为一旦你下载了源发布，你就独立了。您是否曾经在某处乘坐火车，需要快速查看模块 X 的文档但无法访问 Internet 的情况？然后你如释重负地意识到文档已经在本地了。
这方面的另一个重点是，您与代码捆绑在一起的文档肯定适用于代码版本。代码和文档是同步的。
尤其是关于 Python 的另一件事：您可以使用 Sphinx 编写文档，然后在安装包的过程中根据文档源构建漂亮的 HTML 输出。我已经看到各种 Python 包正是这样做的。
关于测试：
想象一下，测试捆绑在源版本中并且很容易由用户运行（您应该记录如何执行此操作）。然后，如果用户发现您的代码存在不容易追踪的问题，他可以简单地在他的环境中运行单元测试，看看是否至少通过了这些测试。如果不是，那么您在指定代码的行为时可能做出了错误的假设，这很值得了解。我想说的是：如果你让用户执行单元测试变得非常简单，这对你作为开发人员来说是非常好的。
于 2013-07-18T11:37:23.743 回答