如何在 GitHub Pages 上托管 Sphinx 文档？

Question

我最近编写了一个 Python 包并使用 Sphinx 生成了一些文档。我将文档添加到项目的 GitHub 存储库中，现在想要托管静态页面。我在网上看到您可以使用 GitHub Pages 来执行此操作。

因此，我确保为公共存储库启用 GitHub Pages，并选择

docs

文件夹作为根目录。

目前，我遇到了：

404 Files not Found Error 

每次我尝试访问项目链接时。

文档目录的当前层次结构如下：

- docs
   - source
       - index.rst
       - installation.rst
       - conf.py
       - examples.rst
   - Makefile

我在网上阅读了一些内容，例如this，这似乎意味着如果您有子目录，可能会出现问题（即对我来说，在这种情况下，问题可能是我有一个单独的

source

目录）在

docs

目录中，而不仅仅是同一目录中的所有文件）。我认为这可能是问题所在，唯一的部分是我不确定如何解决这个问题。

我是否必须选择

source

子目录中的所有文件，然后使用

Makefile

将它们移动到 docs 目录？我该怎么做呢？这一定是我用来在 Git 上跟踪它们的结构，所以也许我必须更改 Git 跟踪它们的方式？

任何资源或示例的链接将不胜感激。

编辑：我正在查看这个存储库，特别是文档似乎都托管在 GitHub 页面上，并以

.rst

文件格式上传到存储库。这可能与 Jekyll 或其他什么有关吗？

---

更新：

编辑2：我最终从存储库中删除了

.rst

文件（从git中取消跟踪它们）并将

.html

文件推送到构建目录中。由于 GitHub Pages 要求文档位于根

/docs

目录中，我只是将

.html

文件复制到存储库中的

/docs

根文件夹中。然而，我遇到的问题是，现在主题没有正确构建，我只得到了

index.html

构建的骨架版本。

我已经确定这可能与未包含的

_static

文件或正确构建主题所需的其他一些文件有关。我的问题是，这个项目的目录结构应该是什么样子？

例如，我们有：

/docs
   _static
   index.html

我们需要包含哪些文件才能正确构建 Sphinx 文档 以及每个文件/文件夹应位于

/docs

根目录中的哪个级别？

换句话说，我在这篇博文中详细了解了与主题相关的问题。我尝试简单地将目录中的

_static

文件夹移动到与

index.html

文件相同的级别，但这似乎并没有解决问题。

Answer 1

既然您指出了您正在查看的存储库，现在就可以知道该作者如何使一切正常工作。

实际的文档生成/部署工作流程位于 CircleCI 配置中，https://github.com/amueller/dabl/blob/main/.circleci/config.yml

它只是执行以下操作，

1. 使用

   build_doc.sh

   生成 HTML 页面和其他工件。
2. 使用

   push_doc.sh

   将所有工件复制到启用 GitHub Pages 的存储库，https://github.com/amueller/amueller.github.io

就像我评论的那样，该作者仅托管由 Sphinx 生成的 HTML 页面和其他工件（这正是 GitHub Pages 所期望的），而不是 reStructuredText 源文件。

Answer 2

我遇到了类似的问题。在文档中添加文件 .nojekyll 为我解决了这个问题。

您还可以在每次推送（或发布）时使用 sphinx-docs github action

自动生成文档