将自定义脚本添加到 sphinx 中的某些文档

Question

我有这个用于在 sphinx 中生成文档（html）的文件夹结构：

doc-root
- static (custom.css, custom.js)
- doc-1 (*.rst)
- doc-2 (*.rst)
- doc-3 (*.rst)
conf.py
index.rst (toctree for doc-1, doc-2 and doc-3)

我正在生成 htmls 并希望将 custom.js 添加为仅用于 doc-2 的脚本标记。

我尝试在 root conf.py 的 setup(app) 中添加 app.add_javascript('custom.js')，但是 sphinx 将 custom.js 添加到所有生成的 html 中。

我添加了一个 doc-1/conf.py 并添加了 setup(app)，但它从未被调用，因为我使用根目录中的 -c 选项从根目录生成 html。

有没有办法通过使 sphinx 从其子文件夹中尊重 conf.py 或通过在根 conf.py 中提供逻辑来实现这一点？

Answer 1

我想出了一个解决方案：

将 custom.js 添加到_static/文件夹； 然后创建一个包含内容的doc-root/templates/layout.html文件：

{% extends "!layout.html" %}

{%- block extrahead %}
<meta name="sourcename" content="{{ sourcename }}" />
{% if "doc-2" in sourcename %}
  <script type="text/javascript" src="./_static/custom.js"></script>
{% endif %}
{% endblock %}

确保 src attr 指向正确的相关 js 文件。 我添加了元标记只是为了回应当前的文档值。 当 sourcename 变量包含 doc-2/index.rst.txt 值时，将添加脚本。