Python Sphinx锚点在任意一行

Question

如何使用Sphinx在ReST中的任意一行设置锚点引用？

更清楚,这是一个例子:

A title with an anchor
----------------------

some stuff

这将创建一个标题,A title with an anchor并在该行的末尾添加一个额外的悬停 ¶,就像标题一样.

Answer 1

您可以使用以下角色执行此操作ref:http: //sphinx-doc.org/markup/inline.html#role-ref

具体阅读第二个要点,它解决了如果未在标题之前放置引用会发生什么.

例如,在一个名为example.rstthis 的文件中,您将使用以下方法:

.. _arbitrary-anchor:

Some Arbitrary Line
    This is actually a definition

标签"任意锚"必须在整个文档中是唯一的.要在文档中的某处引用此锚点,您可以执行以下操作:

Lorem ipsum :ref:`here is the anchor link <arbitrary-anchor>` dolor sit amet

不幸的是,当您将鼠标悬停在引用行上时,此锚点不会显示,但您应该能够使用显式链接访问它http://example.com/example.html#arbitrary-anchor

既然你提到了定义 - 值得注意的是,有一个叫做的角色term可以让你引用词汇表中的定义.

有关如何使用它的示例,请参阅:http://sphinx-doc.org/glossary.html#term-role

以及如何在第3段中引用它:http: //sphinx-doc.org/domains.html#domains

最后,如果你需要在段落的中间插入一个锚,一个办法做到这一点是通过创建一个明确的<a id=#sample>inline anchor</a>使用raw role: http://docutils.sourceforge.net/docs/ref/rst/roles.html#生的

编辑:

还有一个选择.这将创建一个锚点和悬停效果.

.. rst:role:: Sample rst role

    This is a sample definition which links back to its anchor :rst:role:`Sample rst role`

这是一个有趣的指令,我已经使用了一段时间了.当我查看此页面的来源时,我发现了它:

http://sphinx-doc.org/markup/inline.html#inline-markup

http://sphinx-doc.org/_sources/markup/inline.txt

当您悬停时,文本看起来像这样:

单击链接后,文本如下所示:

此选项不太理想,因为它显示:定义的左侧和右侧.但它很好,因为它创建了一个锚并悬停在不是标题的东西上(所以它也不会出现在TOC中,这正是我想要的)