带有 Sphinx 生成文档的 Github 页面无法正确显示 HTML答案

【问题标题】：Github Pages with Sphinx generated documentation not displaying HTML correctly带有 Sphinx 生成文档的 Github 页面无法正确显示 HTML
【发布时间】：2020-10-18 21:47:25
【问题描述】：

我一直在尝试以readthedocs.org 提供的主题在 Github 页面上为我们的存储库发布 Sphinx 生成的文档。

经过几次尝试后，我设法通过将 Sphinx 生成的 HTML 文件上传到存储库的 gh-pages 分支中使其在线。

获得这个：

https://takeqontrol.github.io/qontrol_api/

这看起来很糟糕，通过阅读文档删除了主题的所有自定义。

以下是您打开链接时看到的示例：

但是如果我在我的计算机上打开这些 HTML 文件，页面看起来就像我想要的那样。下面是一个在本地显示完全相同的 HTML 的示例：

有人知道发生了什么吗？或者甚至指出我可以找到解释的地方？

所有代码都在这里：https://github.com/takeqontrol/qontrol_api 在两个分支中。

【问题讨论】：

这能回答你的问题吗？ Using github actions to publish documentation
很遗憾没有。无论如何，谢谢。
如果有帮助，我找到了一个不同的解决方案，我发布了here

标签： github github-pages python-sphinx read-the-docs

【解决方案1】：

我为此奋斗了 9 个小时，才发现是 _static 文件夹中的 下划线 导致了问题。

你需要by pass Jekyll on github pages。

为此，请将一个空的 .nojekyll 添加到您的 gh-pages 分支。（见example）

【讨论】：

一个空的.nojekyll 文件不是你的意思吗？如果我告诉 GitHub Pages 使用 /docs 作为发布源，这对我在 docs 文件夹下也有效。
sphinx.ext.githubpages Sphinx 扩展似乎有助于自动执行此操作。

【解决方案2】：

我遇到了类似的问题，然后发现了这个，它为我解决了这个问题：

Python Sphinx css not working on github pages

似乎为 _sources + _static 文件夹使用下划线导致了问题。需要相应地在 html 文件中使用它们重命名文件夹和路径。

【讨论】：

嗨，斯科特，感谢您的回答，我尝试这样做，现在页面不再显示。我只得到未找到的 404 错误页面。仍然在本地我可以完美地可视化网页。