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

4
我最近编写了一个Python包,并使用Sphinx生成了一些文档。我将文档添加到项目的GitHub存储库中,现在想托管静态页面。我在网上看到可以使用GitHub Pages来实现这一点。
因此,我确保为公共存储库启用了GitHub Pages,并选择了docs文件夹作为根目录。
目前,我遇到了一个问题:
404 Files not Found Error 

每次我尝试访问项目链接时都会出现问题。
目前docs目录的层次结构如下:
- docs
   - source
       - index.rst
       - installation.rst
       - conf.py
       - examples.rst
   - Makefile

我在网上读了一些东西,比如this,它似乎意味着如果您有子目录(例如,在我的情况下,问题可能是我在docs目录中有一个单独的source目录,而不仅仅是所有文件都在同一个目录中),可能会出现问题。我认为这可能是问题所在,唯一的问题是我不确定如何解决。
我是否需要选择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根目录中应该处于什么级别?

换句话说,我遇到了与this blog post中详细描述的主题相关的问题。我尝试将_static文件夹简单地移动到具有index.html文件的级别,但这似乎没有解决问题。


GitHub Pages只能托管静态HTML页面和/或Jekyll脚本。因此,在您的情况下,您只能从reStructuredText源生成HTML页面,然后将这些HTML页面(和支持文件)推送到Git存储库上以在GitHub Pages上显示。托管reStructuredText源代码是行不通的。 - Lex Li
有没有示例的链接?我看到了一些存储文档的repos,但似乎没有上传HTML文件到这个repo。 - Ethan
这实际上取决于您所指的存储库。许多此类存储库直接托管reStructuredText并链接到ReadTheDocs进行渲染,而不是GitHub Pages。 - Lex Li
1个回答

2
由于您指出了您正在查看的存储库,现在可以确定该作者如何使所有内容工作。
实际的文档生成/部署工作流程在 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 源文件。

谢谢您的回复。鉴于这些信息,重新上传/替换存储库中所有.rst文件为HTML文件是否更容易?这样GitHub页面就会自动捕捉到它们了,对吧? - Ethan

网页内容由stack overflow 提供, 点击上面的
可以查看英文原文,
原文链接