如何将 sphinx 生成的 html 文档上传到 github？答案

【问题标题】：How to upload HTML documentation generated from Sphinx to GitHub?如何将 sphinx 生成的 html 文档上传到 github？
【发布时间】：2010-12-05 22:39:48
【问题描述】：

我刚刚记录了我的大量代码并学习了如何使用 sphinx 来生成文档。我想将它包含到我的 github 项目页面中，但我不知道如何。有人知道现有的教程或简单的步骤吗？

谢谢。

【问题讨论】：

标签： python github python-sphinx

【解决方案1】：

github 将使用他们的github pages 功能为您提供静态内容。本质上，您创建了一个名为 gh-pages 的分支，将静态页面提交到该分支中。然后在 you.github.com/yourproject 上提供这些页面。

请参阅http://pages.github.com/ 的说明。

在 github 上使用 Sphinx 可能会遇到问题，因为 Sphinx 使用的目录带有前导下划线。您可以通过在包含生成的 sphinx html 的目录中添加一个名为 .nojekyll 的文件来解决此问题。

【讨论】：

说明链接已损坏。
.nojekyll 小费是救命稻草。希望我早点读过这个。进一步说明：将其添加到 html 树的根目录。
@Jayesh 上面所说的链接：github.com/blog/572-bypassing-jekyll-on-github-pages

【解决方案2】：

John Paulett's answer 显然是正确的，并且对于大多数用户来说可能已经足够了 (+1)。

或者，您可能想查看 Ben Welsh 的详尽教程 Sphinx documentation on GitHub，它提供了分步说明以及方便的基于 Fabric 的脚本/任务，将它们结合在一起以帮助您开始快速发布文档在您的代码旁边 [...] 通过单个命令。

【讨论】：

GitHub 上的 Sphinx 文档说：you need to create an empty file in the root directory that lets GitHub know you aren’t using Jekyll to structure your site.

【解决方案3】：

github-tools 具有完全符合您要求的功能：

paver gh_pages_create gh_pages_build

请参阅excellent documentation（当然使用自己）了解如何为您的项目设置它。

【讨论】：