Sphinx toctree指令中的外部相对链接

Question

我正在使用Sphinx构建我的文档。我正在使用其他工具作为API参考。我的文档在一个目录中，API引用在目录名api中。

我希望有一个从文档到API参考的链接。我可以添加一个链接到我的toctree链接，这样：

.. toctree::
   :maxdepth: 1

   starting
   glossary
   main-use-case-flow
   API Reference <http://www.example.com/lib/ios/0.1.0/api/>

问题是我不想放入完整路径，我只想放入相对路径api/

如何使用相对路径而不是绝对路径来放置到外部资源的链接？

Answer 1

我找到了一种最老套的方法来做到这一点。基本上，Sphinx允许指向文档的路径或需要http://的绝对路径。事实证明，他们所做的所有验证你的链接是寻找字面上的http://。

*WARNING: toctree contains reference to nonexisting document u'downloads'*
Downloads <../downloads>

但如果你这样做了：

Downloads <../downloads#http://>

没有警告！然而，这确实意味着当用户单击您的链接时，它会将http://片段或命名锚点插入到您的页面链接。如果这不是您的html中的有效命名锚点，它将不会对您的页面做任何操作(除非您的页面包含对命名锚点执行某些操作的javascript )。

Answer 2

在当前版本的Sphinx中，您只需将

.. toctree::

   Title <http://LINK>

它会起作用的。

Answer 3

当我试图将指向(生成的)javadoc的链接添加到我的toctree时，我遇到了这个问题。

我的解决方案是在源码树中的适当位置创建一个伪index.rst，以满足toctree的要求。我发现这个虚假的index.rst文件必须包含一个标题，所以我的文件看起来像这样：

=======================
Java API (All Packages)
=======================

当您运行make时，此文件将被复制到您的构建目录_build/html (或其他目录)中。

然后简单地将其替换为reStructuredText处理后的真实文件。