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

Question

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

因此，我确保为公共(public)存储库启用 GitHub Pages 并选择 docs根目录的文件夹。

目前，我遇到了:

404 Files not Found Error 

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

docs 目录的当前层次结构为:

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

我在网上阅读了一些内容，例如 this这似乎意味着如果你有子目录可能会出现问题(即对我来说，在这种情况下，问题可能是我在 source 目录中有一个单独的 docs 目录，而不仅仅是所有文件在同一目录中)。我认为这可能是问题所在，唯一的部分是我不确定如何解决这个问题。

我是否必须选择 source 中的所有文件？子目录并将它们移动到带有 Makefile 的文档目录中？我该怎么做？这一定是我用来在 Git 上跟踪它们的结构，所以也许我必须更改 Git 跟踪它们的方式？

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

编辑:我正在查看 this repo特别是文档似乎都托管在 GitHub 页面上并上传到 .rst 中的 repo。文件格式。这可能与 Jekyll 或其他什么有关吗？

---

更新:

编辑 2:我最终删除了 .rst来自 repo 的文件(从 gi​​t 中取消跟踪它们)并推送 .html构建目录中的文件。由于 GitHub Pages 要求文档位于根目录中 /docs目录我刚刚复制了 .html文件放入 /docs repo 中的根文件夹。但是，我遇到的问题是现在主题没有正确构建，我只得到了 index.html 的骨架版本。构建。

我已经确定这可能与 _static 有关未包含的文件或正确构建主题所需的一些其他文件。我的问题是，这个项目的目录结构应该是什么样的？

例如，我们是否有:

/docs
   _static
   index.html

要正确构建 Sphinx 文档，我们需要包含哪些文件以及每个文件/文件夹在 /docs 中应该处于什么级别？根目录？

换句话说，我得到了 this blog post 中详述的与主题相关的问题.我尝试简单地移动 _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

所以就像我评论的那样，该作者仅托管 HTML 页面和 Sphinx 生成的其他工件(这正是 GitHub Pages 所需要的)，而不是 reStructuredText 源文件。