8

因此,我在 pypi 上发布了一个小型库,更多的是作为练习(“看看它是如何完成的”)而不是其他任何东西。

我已经在 readthedocs 上上传了文档,并且我的 git repo 中有一个测试套件。

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

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

4

1 回答 1

5

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

关于文档:

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

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

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

关于测试:

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

于 2013-07-18T11:37:23.743 回答