Can a <target> node be used to point to a :ref:-style target?

[Matthias Geier]

Hello list.

I want to write RST files that use links to reference labels like this_.

.. _this: a-reference-label

The resulting document has <reference> nodes and corresponding
<target> nodes. The <target> node for the above example has an
attribute refuri="a-reference-label".

I would like to create a Transform that changes the <target> node in a
way that the link that is created in the end points to the reference
named "a-reference-label".
The result should look as if I had used :ref:`a-reference-label` in
the first place.

Is that possible?

If not, I think I'll have to traverse all <reference> nodes, search
for their corresponding <target> nodes and replace each <reference>
node with a <pending_xref> node with the appropriate "refuri"
attribute.

But for this, I have yet another question:

Is there somewhere a list/dict with all the <target> nodes in the
current document?

cheers,
Matthias

[Komiya Takeshi]

Hi Matthias,

>Is there somewhere a list/dict with all the <target> nodes in the
current document?

All targetable nodes are listed into the nameids attribute of document node.
This is also an answer for another question.

docutils uses the attribute to resolve reference. So you need to
register the new target node before resolving.
To do that, you can use document.note_implicit_target() and
note_explicit_target().

Note: implicit and explicit target are described here.
http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#implicit-hyperlink-targets

In addition, Sphinx also uses the attribute to realize cross
reference. So I suppose note_*_target() API will resolve your case.

For more information, please read the document and source code of
docutils. I've read it again and again.

Thanks,
Takeshi KOMIYA

> --
> You received this message because you are subscribed to the Google Groups "sphinx-dev" group.
> To unsubscribe from this group and stop receiving emails from it, send an email to sphinx-dev+...@googlegroups.com.
> For more options, visit https://groups.google.com/d/optout.

[Matthias Geier]

On Tue, Mar 20, 2018 at 12:26 PM, Komiya Takeshi <i.tk...@gmail.com> wrote:
> Hi Matthias,
>
>>Is there somewhere a list/dict with all the <target> nodes in the
> current document?
>
> All targetable nodes are listed into the nameids attribute of document node.
> This is also an answer for another question.

Thanks a lot, "nameids" (and "ids") was exactly the information I needed!

I ended up using this instead of trying to manipulate the <target> nodes.
This worked much better with my already existing code.

If you are (or someone else on this list is) interested, this is what
I did with your help:
https://github.com/spatialaudio/nbsphinx/pull/173

The idea for this came from a recent posting on this list:
https://groups.google.com/forum/#!topic/sphinx-users/ZoYI_-ZKMDw

You can see the result here:
http://nbsphinx.readthedocs.io/en/local-links/a-normal-rst-file.html
(at some point the URL will change to
http://nbsphinx.readthedocs.io/en/latest/a-normal-rst-file.html)

The links work in Sphinx, but they also work on Github, see
https://github.com/spatialaudio/nbsphinx/blob/7e791655205beebccce65b920d4cf798c8f6d614/doc/a-normal-rst-file.rst

> docutils uses the attribute to resolve reference. So you need to
> register the new target node before resolving.
> To do that, you can use document.note_implicit_target() and
> note_explicit_target().
>
> Note: implicit and explicit target are described here.
> http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#implicit-hyperlink-targets
>
> In addition, Sphinx also uses the attribute to realize cross
> reference. So I suppose note_*_target() API will resolve your case.
>
> For more information, please read the document and source code of
> docutils. I've read it again and again.

Yes, I know, I've read some parts of the docutils documentation over
and over again, but they mostly talk about the behavior and not about
how it is implemented.
I also grep around in the source code a lot, but it's really not that
easy to follow what's happening.

I appreciate your help very much, because I wouldn't be able to find
this information on my own!

cheers,
Matthias

[Komiya Takeshi]

Good to know :-)

Both docutils and Sphinx are hard to understand. I usually find new
features on development.
So let's share the information of them on this list.

Thanks,