Python Sphinx css 在 github 页面上不起作用答案

【问题标题】：Python Sphinx css not working on github pagesPython Sphinx css 在 github 页面上不起作用
【发布时间】：2021-04-12 05:00:21
【问题描述】：

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

这是我的斯芬克斯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/

有什么问题？

【问题讨论】：

不加载任何 CSS 或 JavaScript。对于如何修复它，您可以对 HTML 进行后处理。

标签： python django github-pages python-sphinx

【解决方案1】：

我使用 sphinx/githubpages 来记录我的一个 python 项目。我发现这个blog post 很有帮助。这是我的工作示例docs directory。

在 docs 目录中添加 .nojekyll 文件将解决此问题。这告诉 github 页面不要通过 jekyll 发布文件。有了这个，您不需要更改任何目录名称，它应该使用“_”前缀。

【讨论】：

【解决方案2】：

TL;DR

将.nojekyll 文件添加到存储库的顶级目录 (source)。

与 previous answers 相比，.nojekyll 文件必须位于顶层 - 即使您从 docs/ 提供页面也是如此。

背景：

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

【讨论】：

【解决方案3】：

我也在做同样的事情；问题在于文件夹名称中的下划线。下划线表示ignore the folder。

我用sed修改了。

【讨论】：

【解决方案4】：

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

html_theme = "sphinx_rtd_theme"

但我忘记将其包含在扩展中：

extensions = [
    ...
    "sphinx_rtd_theme",
]

并导入它：

import sphinx_rtd_theme

我能够通过查看控制台错误消息并查看问题所在来解决这个问题：

【讨论】：