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

Question

我正在使用 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/
如何使用相对路径而不是绝对路径来链接到外部资源？

Answer 1

我发现了一种最简单的方法来做到这一点。基本上，Sphinx 允许使用文档路径或需要 http:// 的绝对路径。 .事实证明，他们为验证您的链接所做的一切就是从字面上查找 http:// .

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

但如果你这样做:

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

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