Sphinx:链接到嵌入式二进制文件 (PDF) [英] Sphinx: Linking to Embedded Binary Files (PDFs)

问题描述

我正在使用 sphinx 和 RST 生成一些 HTML 格式的技术文档，但在获取本地 PDF 参考作为超链接时遇到问题.我见过人们使用 :download: 链接到本地​​ PDF，但我将 PDF 嵌入 /docs 目录中以供参考.我不喜欢 :download: 因为它不会在浏览器中内嵌显示 PDF，这需要代表用户执行额外的步骤才能使用.

I'm using sphinx and RST to generate some tech documentation as HTML and having issues getting a local PDF reference to work as a hyperlink. I've seen people use :download: to link to local PDFs, but I'm embedding the PDFs inside a /docs directory for reference. I don't like :download: because it doesn't display the PDF inline in the browser which requires an extra step on the users' behalf for consumption.

sphinx-build -b html 不会复制任何文件，除非它们在 config.py 钩子 html_static_path 或 html_extra_path 中指定 - 即便如此，它们也会被放到 root 目录或 _static 文件夹中.

sphinx-build -b html does not copy any files unless they are specified in config.py hook html_static_path or html_extra_path - and even then they are dropped to the root directory or _static folders.

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

Is there a suggested approach for embedding linked binary files within sphinx or is this a poor practice? Often times the links are to slide decks or design diagrams that are not hosted anywhere else.

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

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

推荐答案

我想出的解决方案是将 PDF 添加到 html_static_path 并引用 _static 输出链接中的路径，而不是它在源中所在的 docs 路径.现在 PDF 可以在浏览器中打开，而无需下载即可查看.

The solution I came up with was to just add the PDFs to html_static_path and reference the _static output path in the link instead of the docs path where it lives in the source. Now PDFs open up in the browser instead of having to download them to view.

如果有一个 sphinx 扩展/指令来处理这个会很棒(:download-inline:).

Would be great if there was an sphinx extension / directive to handle this (:download-inline:).

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

agile-101.rst

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

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

这篇关于Sphinx:链接到嵌入式二进制文件 (PDF)的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！