任意线上的Python狮身人面像锚点 [英] Python Sphinx anchor on arbitrary line

问题描述

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

How can I set an anchor reference at an arbitrary line in ReST using Sphinx?

更清楚的是，这里有一个例子：

To be more clear, here is an example:

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

some stuff

这将创建一个标题 A标题与锚点，并在行尾添加一个额外的

this will create a heading A title with an anchor and add an extra on-hover ¶ character at the end of the line, which will be an anchor reference to that line/heading.

现在在以下情况...

Now in the following case...

``some arbitrary line``
    this is actually a definition

...我想要一个锚点一些任意行，与标题相同。

...I want to have an anchor for some arbitrary line, the same way as for the heading.

推荐答案

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

You can do this with a role called ref: http://sphinx-doc.org/markup/inline.html#role-ref

具体阅读第二个项目符号，其中说明如果引用未放在标题之前会发生什么。

Specifically read the 2nd bullet point which addresses what happens if the reference is not placed before a title.

例如，在文件中称为 example.rst 这是您将如何使用：

For example, in a file called example.rst this is how you would use:

.. _arbitrary-anchor:

Some Arbitrary Line
    This is actually a definition

标签任意锚在文档中必须是唯一的。要在文档中的某个地方引用此锚点，您可以执行以下操作：

The label "arbitrary-anchor" has to be unique through out the document. To reference this anchor somewhere in the document, you would do something like this:

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

不幸的是，这个锚点不会显示出来悬停，但您应该可以使用 http://example.com/example.html#arbitrary-anchor

Unfortunately, this anchor will not show up when you hover over the referenced line, but you should be able to access it using an explicit link to http://example.com/example.html#arbitrary-anchor

既然你提到定义 - 还值得注意的是一个名为术语的角色，您可以在术语表中引用定义。

Since you mention definitions - it is also worth noting that there is a role called term which lets you reference a definition in the glossary.

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

For an example of how to use this, see: http://sphinx-doc.org/glossary.html#term-role

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

and how this is referenced in the 3rd paragraph of: http://sphinx-doc.org/domains.html#domains

最后，如果您需要在段落的中间插入一个锚点，一种方法是创建一个显式的< a id =＃sample>内联锚点< / a> 通过使用原始角色：
http://docutils.sourceforge.net/docs/ref/rst/roles.html#raw

Lastly, if you need to insert an anchor in the middle of a paragraph, one way to do it is by creating an explicit <a id=#sample>inline anchor</a> by using a raw role: http://docutils.sourceforge.net/docs/ref/rst/roles.html#raw

编辑：

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

There is one more option. This will create an anchor and the hover effect.

.. rst:role:: Sample rst role

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

这是一个有趣的指令，我一直在使用一段时间。当我查看此页面的源代码时，我发现了这一点：

This is a funny looking directive that I've been using for a while now. I found it when I was looking at the source of this page:

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

< a href =http://sphinx-doc.org/_sources/markup/inline.txt =nofollow noreferrer> http://sphinx-doc.org/_sources/markup/inline.txt

当您悬停时，文字如下所示：

点击链接后，文字如下所示：

此选项不太理想，因为它在定义的左侧和右侧显示：。但是这很好，因为它创建了一个锚点并将其悬停在不是标题的东西上（因此它也不会显示在TOC中，这正是我想要的）

This option is less that ideal because it displays the : to the left and right of the definition. But it is nice because it creates an anchor and hover on something that's not a title (so it doesn't show up in the TOC as well, which is exactly what I wanted)

这篇关于任意线上的Python狮身人面像锚点的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！