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/

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

score 26 · Accepted Answer

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

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

但如果你这样做：

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

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

score 9 · Accepted Answer

在当前版本的狮身人面像你可以把

.. toctree::

   Title <http://LINK>

它会起作用。

score 4 · Accepted Answer

当我尝试将指向（生成的）javadocs 的链接添加到我的toctree.

我的解决方案是在我的源代码树中的适当位置创建一个假冒index.rst，以满足toctree. 我发现假index.rst文件必须包含标题，所以我的文件如下所示：

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

当你运行时make，这个文件被复制到你的构建目录中，_build/html（或其他）。

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

score -6 · Accepted Answer

-6

以下语法对我有用：

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

于 2015-01-20T08:53:45.900 回答

4 回答 4