Sphinx PDF 文档中指向外部 git 存储库的超链接答案

【问题标题】：hyperlink to an external git repository in Sphinx PDF documentationSphinx PDF 文档中指向外部 git 存储库的超链接
【发布时间】：2013-09-01 15:42:54
【问题描述】：

以表格形式指向 git 存储库的外部超链接

.. _Git repo: git://github.com/migueldvb/repo.git

在 HTML 文档中正确显示，但在 PDF 文件中不显示。运行python setup.py sphinx_build -b latex生成LaTeX文件时出现警告：

unusable reference target found git://github.com/...

如何在 Sphinx 生成的 PDF 文档中包含指向 git 存储库的超链接？

【问题讨论】：

标签： python python-sphinx

【解决方案1】：

这似乎有效：

.. raw:: latex

    \href{git://github.com}{GitHub}

.. raw:: html

    <a href="git://github.com">GitHub</a>

编辑：我查看了sphinx的源码，在visit_reference方法的文件sphinx/writers/latex.py中产生了警告信息，定义如下：

def visit_reference(self, node):
        uri = node.get('refuri', '')
        # ...
        elif uri.startswith('mailto:') or uri.startswith('http:') or \
                 uri.startswith('https:') or uri.startswith('ftp:'):
            self.body.append('\\href{%s}{' % self.encode_uri(uri))
        else:
            self.builder.warn('unusable reference target found: %s' % uri,
                              (self.curfilestack[-1], node.line))
            self.context.append('')

因此协议是硬编码的，因此我认为不使用原始数据或更改 sphinx 源以使“未知”链接正常工作是没有选择或简单的方法的。

我在源码中加了一行git协议：

def visit_reference(self, node):
        uri = node.get('refuri', '')
        # ...
        elif uri.startswith('mailto:') or uri.startswith('http:') or \
                 uri.startswith('git:') or \
                 uri.startswith('https:') or uri.startswith('ftp:'):
            self.body.append('\\href{%s}{' % self.encode_uri(uri))

现在 'make latexpdf' 和 'make html' 正在生成带有以下来源的有效 git 链接的文档：

Test Link
=========

This is a paragraph that contains `a link`_.

.. _a link: git://git.kernel.org/pub/scm/linux/kernel/git/next/linux-next.git

【讨论】：

谢谢。我想要一个适用于 HTML 和 PDF 文档的解决方案
查看我的编辑。我知道它并不漂亮，但我找不到更好的方法让它发挥作用。 :)
谢谢，但我无法同时处理 HTML 和 PDF。
请看我的新编辑。我在源代码中修复了它，希望没有副作用。 :)
太好了，谢谢你！