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

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

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

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

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

然后在reStructuredText处理后将其替换为 real 文件。

Answer 3

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

.. toctree::

   Title <http://LINK>

它会起作用。

Answer 4

以下语法适用于我：

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