带有链接作为脚注的可打印 PDF 输出 [英] Printable PDF output with links as footnotes

问题描述

我正在使用 sphinx 生成 Python 项目的文档，并且我大量使用外部链接.我想构建 html 和 latexpdf 输出，这些输出作为可点击链接(这是默认设置)，但也是将打印的 PDF 版本，这些链接显示放在脚注中.

I'm using sphinx to generate the documentation of a python project and I'm making heavy use of external links. I'd like to build html and latexpdf outputs with these as clickable links (which is the default), but also a PDF version that will be printed, with these links showing up in footnotes.

简而言之:有没有办法在 .rst 文件中编写外部链接，如下所示:

In short: is there a way to write external links in a .rst file like this:

Ask a question on `my favorite Q&A website <http://stackoverflow.com/>`_.

并有一个特殊的输出，可以将其解释为像这样写的脚注:

and have a special output that will interpret this as if it was a footnote written like this:

Ask a question on my favorite Q&A website [#SO]_.

.. [#SO] http://stackoverflow.com/

同时在其他输出中保持正常行为(没有脚注的可点击链接)?

while keeping the normal behavior (clickable link without a footnote) in other outputs?

推荐答案

Jongware 的评论让我看到了一些我没有看到的 sphinx 文档，我意识到实际上有一个配置变量可以满足我的需求:

Jongware's comment made me look at parts of the sphinx documentation I didn't see, and I realized there actually is a configuration variable that does what I want:

latex_show_urls = 'footnote'

由于我希望能够在不更改 conf.py 文件的情况下生成通常的 pdf 和带有脚注的 pdf，因此我保留了默认值并将以下规则添加到 sphinx 的 Makefile 中:

As I wanted to be able to generate the usual pdf and the one with the footnotes without changing the conf.py file, I left the default value and added the following rule to the sphinx's Makefile:

.PHONY: printpdf
printpdf: SPHINXOPTS+=-Dlatex_show_urls=footnote
printpdf: latexpdf

此规则调用常规的 latexpdf 规则，将 -Dlatex_show_urls=footnote 添加到赋予 sphinx-build 的选项.

This rule calls the regular latexpdf rule, adding -Dlatex_show_urls=footnote to the options given to sphinx-build.

有了这个，我们可以生成要打印的PDF(带脚注):

With this, we can generate the PDF to be printed (with footnotes) with:

make printpdf

如果我们想要一个普通的 PDF，没有潜在的大量和(这里)无用的脚注，常规规则仍然可以:

And if we want a regular PDF, without the potentially numerous and (here) useless footnotes, the regular rule still does it:

make latexpdf

这篇关于带有链接作为脚注的可打印 PDF 输出的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！