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

【问题标题】：External Relative Link in Sphinx toctree directiveSphinx toctree 指令中的外部相对链接
【发布时间】：2015-03-14 19:30:03
【问题描述】：

我正在使用Sphinx 来构建我的文档。我正在使用其他工具进行 API 参考。我在一个目录中有我的文档，其中的目录名称 api 中有 API 参考。

我想要从文档到 API 参考的链接。我可以向我的目录树链接添加一个链接：

.. toctree::
   :maxdepth: 1

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

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

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

【问题讨论】：

【解决方案1】：

在当前版本的 Sphinx 中你可以放

.. toctree::

   Title <http://LINK>

它会起作用的。

【讨论】：

【解决方案2】：

当我尝试将指向（生成的）javadocs 的链接添加到我的toctree 时遇到了这个问题。

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

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

当您运行 make 时，此文件会复制到您的构建目录 _build/html（或其他）中。

然后简单地用reStructuredText处理后的real文件替换它。

【讨论】：

【解决方案3】：

我发现了一种最骇人听闻的方法来做到这一点。基本上，Sphinx 允许文档路径或需要http:// 的绝对路径。事实证明，他们为验证您的链接所做的一切就是寻找字面意义上的http://。

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

但如果你这样做：

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

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

【讨论】：

【解决方案4】：

以下语法适用于我：

`Page Title <../relative/path.html>`

【讨论】：

嗨，我已经检查过了，但这在 ..toctree:: 指令中不起作用。我收到此错误：警告：toctree 包含对不存在文档 u'Page Title <../relative/path.html>' 的引用
我只在普通部分中使用了它，而不是在 toctree 指令中。