Sphinx：链接到嵌入式二进制文件 (PDF)

Question

我正在使用 sphinx 和 RST 生成一些 HTML 格式的技术文档，但在获取本地 PDF 参考作为超链接时遇到问题。我见过人们使用

:download:

链接到本地 PDF，但我将 PDF 嵌入到

/docs

目录中以供参考。我不喜欢

:download:

，因为它不会在浏览器中显示内联 PDF，这需要代表用户执行额外的步骤才能使用。

sphinx-build -b html

不会复制任何文件，除非在

config.py

钩子

html_static_path

或

html_extra_path

中指定它们 - 即使这样它们也会被拖放到

root

目录或

_static

文件夹中。

是否有建议的方法在 sphinx 中嵌入链接的二进制文件，或者这是一个糟糕的做法？通常，这些链接指向未在其他任何地方托管的幻灯片或设计图表。

链接 PDF 的 RST 示例

.. important:: View the agile course on scrum basics

    - View `these slides to dive deeper into Agile Basics <docs/agile-101.pdf>`_. 

Answer 1

我想出的解决方案是将 PDF 添加到

html_static_path

并引用链接中的

_static

输出路径，而不是它在源中所在的

docs

路径。现在，PDF 可以在浏览器中打开，而无需下载才能查看。

如果有一个 sphinx 扩展/指令来处理这个问题那就太好了 (

:download-inline:

)。

conf.py

html_static_path = ['_static', 'agile-101/docs']

敏捷-101.rst

.. important:: View the agile course on scrum basics

- View `these slides to dive deeper into Agile Basics <../_static/agile-101.pdf>`_. 

Answer 2

使用 MySt 解析器的解决方案

使用自定义外部 URL 解析，我们可以在

conf.py

中创建自定义 URL，并使用

html_extra_path

将要链接的文件复制到目录的根目录。假设文件

_extra/file.html

存在，我们可以在

conf.py

中使用以下几行：

# These files provided here are simply copied to the root.
html_extra_path = ["_extra"]

myst_url_schemes = {
  "local": "./{{path}}#{{fragment}}",
}

然后我们可以链接到 HTML 文件的片段，如下所示：

[Local link](local:file.html#section1)

<local:file.html#section1>

进一步使用定制的外部URL

我还使用自定义的外部 URL 来链接到源存储库上的目录，并缩短到常用文档的链接，如下所示：

myst_url_schemes = {
  "isa": "./unpriv-isa-asciidoc.html#{{fragment}}",
  "repo": html_theme_options["repository_url"]
  + "/-/tree/main/{{path}}#{{fragment}}",