如何正确显示从 Sphinx 文档生成器生成的 pdf 中的超链接答案

【问题标题】：How to correctly show hyperlinks in pdf generated from Sphinx documentation builder如何正确显示从 Sphinx 文档生成器生成的 pdf 中的超链接
【发布时间】：2020-08-13 13:47:20
【问题描述】：

在 Sphinx 文档环境中，我正在使用 pdflatex 创建一个 pdf 文档。

为了在源文件之间导航，我在一些文件中添加了使用label 和ref 的链接，它们在HTML 文档中工作得非常好。但是，上述链接不会出现在生成的 pdf 文件中。

我正在复制（部分）我的 .rst 文件，它们之间有 reference：

文件define_ques_list.rst（在此文件中我将文件称为capa.rst）

###################
Question List
###################

**Definition**

Question lists are multilingual collections of questions that are answered during the exe...

:ref:`CAPA <corr-n-prev-action-capa-label>`

.. index:: question list

文件capa.rst

.. _corr-n-prev-action-capa-label:

##########################
CAPA
#########################


Corrective Actions/Preventive Actions
-------------------------------------

**Definition**

*Corrective Actions*

These are actions that are deemed necessary to eliminate the cause of errors that were determined dur...

*Preventive Actions*

These are actions that are deemed necessary to eliminate the causes of possible errors before they ...

.. index:: corrective action CAPA

我检查了文件*.tex 中的（相关）内容，可以看到以下内容：

\chapter{Question List}
\label{\detokenize{modules/definitions/define_ques_list:question-list}}\label{\detokenize{modules/definitions/define_ques_list:question-list-href-label}}\label{\detokenize{modules/definitions/define_ques_list::doc}}
\sphinxstylestrong{Definition}

Question lists are multilingual collections of questions that are answered during the exe...

\DUrole{xref,std,std-ref}{CAPA}    <= This is the hyperlink as translated?

\index{question list@\spxentry{question list}}\ignorespaces

我的问题是：为什么我的 pdf 文件中缺少超链接？

【问题讨论】：

其实我已经运行了很多次make latexpdf，但是没有任何变化（链接没有出现）。 make latexpdf 运行期间没有错误或警告。 toctree 中不存在的文件在创建 html 文档 (make html) 期间显示为警告。但我相信这些不会对实际导航造成问题（因为我能够在 HTML doc 中的文件之间导航）。一个ref。
"目录树中不存在的文件..."。我认为这可能是问题所在。如果具有交叉引用目标的文件不在目录树中，则交叉引用不起作用。我可以重现它。
但至少 hyperlink 必须出现在 pdf 中，不是吗？ 或者我错了。 我试图将其中一个文件包含在一个已经是 toctree 一部分的文件中。我会在一分钟内回来。
否，无法像完成here 那样添加对调用文件的引用。提出：WARNING: duplicate label corr-n-prev-action-capa-label, other instance in /.../docs/modules/definitions/capa.rst。系统指向我的是什么？什么是重复？
查看我生成的代码，我有一个\phantomsection\label\ 作为目标，在\DUrole 之前有一个\sphinxcrossref。但这可能是由于狮身人面像版本不同。我的 RST 语法是一样的，我只使用_ 而不是-，但我不相信这可能是原因。

标签： hyperlink python-sphinx pdflatex

【解决方案1】：

感谢@mzjn 和@Trendfischer，提出了以下解决方案：

使用 index.rst 中的指令 :hidden:，将 referred 添加到文件 capa.rst 中，如图所示：

index.rst

.. xyz documentation master file, created by
   sphinx-quickstart on...
   You can adapt this file....

XYZ documentation
===================

.. toctree::
   :maxdepth: 2
   :caption: Help Contents:

   modules/abc.rst
   modules/definitions/define_ques_list.rst
   help_on_help.rst

.. toctree::    <= New line
   :hidden:     <= New line

   modules/definitions/capa.rst.   <= New line

通过这种安排，我现在可以在生成 pdf 文件时获取到被调用文件 (capa.rst) 的超链接。

【讨论】：

超链接在没有:hidden:的情况下也可以工作；关键是在 toctree 指令中有对 capa.rst 的引用。