Python Sphinx anchor on arbitrary string
How to set anchor anchor on an arbitrary line in ReST using Sphinx?
To be more clear, here's an example:
A title with an anchor
----------------------
some stuff
this will create a header A title with an anchor
and add an extra character on hover ¶
at the end of the line, which will be an anchor to that line / header.
Now in the next case ...
``some arbitrary line``
this is actually a definition
... I want to have an anchor for some arbitrary line
, the same as for a header.
source to share
You can do this with a function ref
:
http://sphinx-doc.org/markup/inline.html#role-ref
In particular, read the second bullet point, which looks at what happens if the link doesn't fit before the heading.
For example, in a file named example.rst
like this, you can use:
.. _arbitrary-anchor:
Some Arbitrary Line
This is actually a definition
The custom anchor label must be unique in 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
Unfortunately this anchor won't show if you hover over the referenced string, but you must be able to access it using an explicit reference tohttp://example.com/example.html#arbitrary-anchor
Since you are mentioning definitions , it is also worth noting that there is a role called term
that allows you to reference the definition in the glossary.
An example using this: http://sphinx-doc.org/glossary.html#term-role
and as stated in the third paragraph: http://sphinx-doc.org/domains.html#domains
Finally, if you need to insert an anchor in the middle of a paragraph, one way to do it is to create an explicit one <a id=#sample>inline anchor</a>
with raw role
:
http://docutils.sourceforge.net/docs/ref/rst/roles.html#raw
EDIT:
There is another option. This will create a snapping and hovering 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 fun directive I've been using for a while. I found it while 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 over:
The text looks like this as soon as you click on the link:
This option is less ideal because it displays to the :
left and right of the definition. But this is good because it creates a binding and hovers over something that is not a header (so it also doesn't show up in the TOC, which is exactly what I wanted)
source to share