网络资源（CSS/JS/字体）#

这个主题包含多个网络资源，以简化开发和设计。我们资源编译的配置在 webpack.config.js 文件中。

编译并打包资源#

当资源被编译后，静态版本会被放置在主题的静态文件夹中的各个位置：

src/pydata_sphinx_theme/theme/pydata_sphinx_theme/static

对于许多资源，系统会生成 <hash> 并将其附加到主题HTML模板中资源引用的末尾。这样可以确保在用户升级主题后再次访问您的网站时，能够提供正确的资源版本。

要编译资源并将其与主题打包，请运行以下命令：

$ tox -e run compile

样式（SCSS）和脚本（JS）#

CSS/JS 资源有两个相关的位置：

  • src/pydata_sphinx_theme/assets/styles 包含 SCSS 资源的源文件。这些文件将被编译为 CSS。

  • src/pydata_sphinx_theme/assets/scripts 包含 JS 资源的源文件。这些文件将被编译为 JS，并导入一些第三方库（如 Bootstrap）。

  • src/pydata_sphinx_theme/theme/pydata_sphinx_theme/static 包含这些资源的编译版本（例如 CSS 文件）。此文件夹未在 .git 历史记录中跟踪，但它会与主题的发行版一起打包。

第三方脚本#

除了我们自己的 CSS 和 JS 外，我们还引入了一些第三方包。例如，Bootstrap、JQuery 和 Popper。这些配置在 webpack.config.js 文件中，并在我们资源文件夹中相应的 SCSS 或 JS 文件中导入。

FontAwesome 图标#

使用了 FontAwesome 6 Free 图标字体的三种“样式”来支持 图标链接 和注释，这是唯一引入的第三方字体。

  • 它作为依赖项在 package.json 中进行管理。

  • 在编译时直接复制到网站的静态文件中，包括许可证。

  • 部分预加载以减少早期图标渲染时的闪烁和伪影。

  • 在 webpack.config.js 中配置。

Jinja 宏#

Webpack 构建会在 static/webpack-macros.html 文件中生成一组 Jinja 宏。

这些宏被导入到主 layout.html 文件中，然后插入到页面的各个位置以链接静态资源。

一些资源被“预加载”，这意味着浏览器在需要这些资源之前就开始请求它们。特别是，我们的 JavaScript 资源在 <head> 中被预加载，而脚本在 <body> 的末尾加载。