Python Sphinx在GitHub Pages上的CSS未生效

Question

我使用Sphinx为 Django 项目创建了文档，并在执行 make html 命令后将 html 文件夹中的内容复制到我的 repo 的 docs/ 文件夹中，并将其推送到 Github。然后，我将此 docs/ 目录设置为 Github Pages，现在已加载文档，但是 css 没有起作用，文档只是没有任何样式的纯文本。

这是我的 Sphinx 的 config.py：

import os
import sys
import django
sys.path.insert(0, os.path.abspath('..'))
os.environ['DJANGO_SETTINGS_MODULE'] = 'PROJECT_NAME.settings'
django.setup()

templates_path = ['_templates']
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
html_theme = 'bizstyle'
html_static_path = ['_static']
BUILDDIR = '.'

这是GitHub页面上文档页面的链接：https://arycloud.github.io/Tagging-Project-for-Machine-Learning-Natural-Language-Processing/

可能出了什么问题？

- Abdul Rehman

---

没有CSS或JavaScript加载。如何修复它，您可以对HTML进行后处理。 - Steve Piercy

Answer 1

我使用sphinx/github pages来记录我的一个Python项目。我发现这篇博客文章非常有帮助。这是我工作中文档目录的一个示例。

在docs目录中添加.nojekyll文件可以解决问题。这告诉Github Pages不要通过jekyll发布文件。有了这个，您就不需要更改任何目录名称，并且应该与“_”前缀一起使用。

- Peter Curran

Answer 2

TL;DR

在您的存储库的顶级目录中添加.nojekyll文件（source）。

与以前的答案相反，即使您从docs/提供页面，.nojekyll文件也必须位于顶级目录。

背景：

Github页面默认使用jekyll。 当jekyll生成网站时，名称以下划线开头的文件不包括在目标中（source，底部）。 这就是为什么如果缺少.nojekyll（禁用jekyll处理），它们不会被github页面提供的原因。

- m8mble

---

对我来说有效，但我在docs/目录下添加了.nojekyll文件，我的Github Pages构建是在docs/目录下启动的。 - Grzegorz Krug

Answer 3

有一个适用于 GitHub Pages 的 Sphinx 扩展：sphinx.ext.githubpages

将其添加到 Sphinx 配置文件 docs/conf.py 中的 extensions 列表中即可。

...

extensions = [
    ...,
    "sphinx.ext.githubpages",
]

...

- Shashanka Prajapati

Answer 4

对我来说，问题在于我使用了Read the Docs主题，并将其添加为HTML主题：

html_theme = "sphinx_rtd_theme"

但是我忘记在扩展中包含它。

extensions = [
    ...
    "sphinx_rtd_theme",
]

并导入它：

import sphinx_rtd_theme

我通过查看控制台错误消息并查看问题所在，成功解决了这个问题：

- Eric Wiener

Answer 5

我也遇到了同样的问题；问题出在文件夹名称中的下划线。下划线意味着忽略该文件夹。

我使用了sed进行修改。

- bertty contreras