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
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.
You can do this with a role called
ref
: https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-refSpecifically read the 2nd bullet point which addresses what happens if the reference is not placed before a title.
For example, in a file called
example.rst
this is how you would use: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:
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.For an example of how to use this, see: http://sphinx-doc.org/glossary.html#term-role
and how this is referenced in the 3rd paragraph of: http://sphinx-doc.org/domains.html#domains
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 araw role
: http://docutils.sourceforge.net/docs/ref/rst/roles.html#rawEDIT:
There is one more option. This will create an anchor and the hover effect.
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
http://sphinx-doc.org/_sources/markup/inline.txt
The text looks like this when you hover:
The text looks like this after you click on the link:
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)