Discussion:
Can a <target> node be used to point to a :ref:-style target?
(too old to reply)
Matthias Geier
2018-03-19 17:28:38 UTC
Permalink
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
--
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.
Komiya Takeshi
2018-03-20 11:26:54 UTC
Permalink
Hi Matthias,
Post by Matthias Geier
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
Post by 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.
Is there somewhere a list/dict with all the <target> nodes in the
current document?
cheers,
Matthias
--
You received this message because you are subscribed to the Google Groups "sphinx-dev" group.
For more options, visit https://groups.google.com/d/optout.
--
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
2018-03-20 23:00:07 UTC
Permalink
Post by Komiya Takeshi
Hi Matthias,
Post by Matthias Geier
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
Post by Komiya Takeshi
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
Post by Komiya Takeshi
Thanks,
Takeshi KOMIYA
Post by 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.
Is there somewhere a list/dict with all the <target> nodes in the
current document?
cheers,
Matthias
--
You received this message because you are subscribed to the Google Groups "sphinx-dev" group.
For more options, visit https://groups.google.com/d/optout.
--
You received this message because you are subscribed to the Google Groups "sphinx-dev" group.
For more options, visit https://groups.google.com/d/optout.
--
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.
Komiya Takeshi
2018-03-21 09:48:36 UTC
Permalink
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,
Post by Matthias Geier
Post by Komiya Takeshi
Hi Matthias,
Post by Matthias Geier
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
https://github.com/spatialaudio/nbsphinx/pull/173
https://groups.google.com/forum/#!topic/sphinx-users/ZoYI_-ZKMDw
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
Post by Komiya Takeshi
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
Post by Komiya Takeshi
Thanks,
Takeshi KOMIYA
Post by 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.
Is there somewhere a list/dict with all the <target> nodes in the
current document?
cheers,
Matthias
--
You received this message because you are subscribed to the Google Groups "sphinx-dev" group.
For more options, visit https://groups.google.com/d/optout.
--
You received this message because you are subscribed to the Google Groups "sphinx-dev" group.
For more options, visit https://groups.google.com/d/optout.
--
You received this message because you are subscribed to the Google Groups "sphinx-dev" group.
For more options, visit https://groups.google.com/d/optout.
--
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.
Loading...