Sphinx在项目中构建了文件

Question

我正在用Sphinx为PYPI打包我的第一个项目。我在docs/source文件夹中使用Sphinx创建了文档。我的问题是：在回购中提供构建的文档是否习惯？通常如何完成？

我问，因为我可以想象许多人不会安装甚至听说过Sphinx。我也希望让自己的生活变得轻松。

Answer 1

文档不是软件。

我不知道PyPI上包含文档的任何包，除了它的README.rst和发行说明。可能有一些包括文档。

如果包有文档，通常会将docs文件夹作为兄弟放在存储库中的软件包源文件夹中。然后在发布到PyPI时，只上传源文件夹。

现在这并不意味着您不能在PyPI版本中包含文档，但是有一些不利因素，包括不必要的下载时间以及用户在安装软件包后无法在文件系统上查找文档。还有其他选择。 Read the Docs是一种流行的服务，可以配置为对存储库的每次更改构建文档，并使其以HTML格式（在线或可下载的.zip），PDF或ePub格式提供。