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

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

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

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

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

然后只需将其替换为reStructuredText 处理后的真实文件即可。

Answer 3

在当前版本的Sphinx中，您可以将

.. toctree::

   Title <http://LINK>

它会工作。

Answer 4

以下语法对我有用：

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