Discussion:
Get output for a cross reference in an extension for the current builder
(too old to reply)
'Rowan Goemans' via sphinx-dev
2018-07-24 02:27:59 UTC
Permalink
Hello everyone,

I am extending a sphinx extension and I want to be able to include cross
references. The plugin itself translates some text to other text which I
can do fine in the visitor functions.

What I want to do is that I want to be able to use a cross reference in my
input text. So something like

.. MyDirective::
Hello everyone, This text will be processed in my plugin. But This
cross reference should still work. :ref:`my-reference-label`


Will be processed. I can detect the :ref:`my-reference-label` in my extension but I cannot find anywhere in how I can turn this into an appropiate link to insert into the body,
so for html that would become a link tag to the appropriate location and for latex it would become a hyperref.

Maybe I am missing something really simple but I can't find it all.

In the sample extension: http://www.sphinx-doc.org/en/master/extdev/tutorial.html#the-event-handlers.
A URL is manually constructured but obviously I don't know at all where the ref is in my case.
Also that would only work for HTML output and not for latex or others.

Any help is appreciated.
--
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-07-24 14:49:40 UTC
Permalink
Hi,

There are no document for that.
Please read the code of `sphinx.roles:XRefRoles`. Sphinx expects a
hyperlink is represented as a pending_xref node having ref*
attributes.
I think `make pseudoxml` also help you to investigate what doctree
Sphinx generates from reST input.

Thanks,
Takeshi KOMIYA

2018-07-24 11:27 GMT+09:00 'Rowan Goemans' via sphinx-dev
Post by 'Rowan Goemans' via sphinx-dev
Hello everyone,
I am extending a sphinx extension and I want to be able to include cross
references. The plugin itself translates some text to other text which I can
do fine in the visitor functions.
What I want to do is that I want to be able to use a cross reference in my
input text. So something like
Hello everyone, This text will be processed in my plugin. But This cross
reference should still work. :ref:`my-reference-label`
Will be processed. I can detect the :ref:`my-reference-label` in my
extension but I cannot find anywhere in how I can turn this into an
appropiate link to insert into the body,
so for html that would become a link tag to the appropriate location and for
latex it would become a hyperref.
Maybe I am missing something really simple but I can't find it all.
http://www.sphinx-doc.org/en/master/extdev/tutorial.html#the-event-handlers.
A URL is manually constructured but obviously I don't know at all where the
ref is in my case.
Also that would only work for HTML output and not for latex or others.
Any help is appreciated.
--
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
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.
'Rowan Goemans' via sphinx-dev
2018-07-25 01:13:26 UTC
Permalink
Thank you for your quick response.

I see now that I could add a 'pending_xref' node. However I simplified in
my original question... My output isn't text but an svg image.

The input text contains the cross references. These have to be resolved in
the text version. Then a tool translates the text to svg.

This means I can't use the pending_xref node. Is there any way to do what I
want?

Rowan Goemans
Post by 'Rowan Goemans' via sphinx-dev
Hello everyone,
I am extending a sphinx extension and I want to be able to include cross
references. The plugin itself translates some text to other text which I
can do fine in the visitor functions.
What I want to do is that I want to be able to use a cross reference in my
input text. So something like
Hello everyone, This text will be processed in my plugin. But This
cross reference should still work. :ref:`my-reference-label`
Will be processed. I can detect the :ref:`my-reference-label` in my extension but I cannot find anywhere in how I can turn this into an appropiate link to insert into the body,
so for html that would become a link tag to the appropriate location and for latex it would become a hyperref.
Maybe I am missing something really simple but I can't find it all.
In the sample extension: http://www.sphinx-doc.org/en/master/extdev/tutorial.html#the-event-handlers.
A URL is manually constructured but obviously I don't know at all where the ref is in my case.
Also that would only work for HTML output and not for latex or others.
Any help is appreciated.
--
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-07-29 07:36:14 UTC
Permalink
Hi,

Thank you for explanation. I understand.
But all directives are called on reading phase. On the reading phase,
output format is not determined yet.
So you can't resolve hyperlink on this time. `pending_xref` node is
used for "pending" resolution of hyperlinks.
http://www.sphinx-doc.org/en/master/extdev/tutorial.html#build-phases

I think you should resolve them on resolving phase. Please handle
`doctree-read` event to resolve them?

```
def on_doctree_read(app, doctree):
std = app.env.get_domain('std')
for node in doctree.traverse(your_custom_node):
for href in node.get_hyperlinks():
pending_xref = make_pending_xref(href) # create
pending_xref node from hyperref
resolved = std.resolve_xref(pending_xref)
merge_resolved_href_into_node(resolved, node) # merge
resolved href to SVG image
```

How about this way?

Thanks,
Takeshi KOMIYA

2018-07-25 10:13 GMT+09:00 'Rowan Goemans' via sphinx-dev
Post by 'Rowan Goemans' via sphinx-dev
Thank you for your quick response.
I see now that I could add a 'pending_xref' node. However I simplified in my
original question... My output isn't text but an svg image.
The input text contains the cross references. These have to be resolved in
the text version. Then a tool translates the text to svg.
This means I can't use the pending_xref node. Is there any way to do what I
want?
Rowan Goemans
Post by 'Rowan Goemans' via sphinx-dev
Hello everyone,
I am extending a sphinx extension and I want to be able to include cross
references. The plugin itself translates some text to other text which I can
do fine in the visitor functions.
What I want to do is that I want to be able to use a cross reference in my
input text. So something like
Hello everyone, This text will be processed in my plugin. But This
cross reference should still work. :ref:`my-reference-label`
Will be processed. I can detect the :ref:`my-reference-label` in my
extension but I cannot find anywhere in how I can turn this into an
appropiate link to insert into the body,
so for html that would become a link tag to the appropriate location and
for latex it would become a hyperref.
Maybe I am missing something really simple but I can't find it all.
http://www.sphinx-doc.org/en/master/extdev/tutorial.html#the-event-handlers.
A URL is manually constructured but obviously I don't know at all where
the ref is in my case.
Also that would only work for HTML output and not for latex or others.
Any help is appreciated.
--
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
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.
George Irwin
2018-08-17 15:57:12 UTC
Permalink
Hi Rowan,

Did you ever find a solution? It sounds like I'm trying to solve exactly
the same problem (specifically I'm hoping to add to sphinx-plantuml to
allow for xref links to python objects).

Thanks

George
Post by 'Rowan Goemans' via sphinx-dev
Thank you for your quick response.
I see now that I could add a 'pending_xref' node. However I simplified in
my original question... My output isn't text but an svg image.
The input text contains the cross references. These have to be resolved in
the text version. Then a tool translates the text to svg.
This means I can't use the pending_xref node. Is there any way to do what
I want?
Rowan Goemans
Post by 'Rowan Goemans' via sphinx-dev
Hello everyone,
I am extending a sphinx extension and I want to be able to include cross
references. The plugin itself translates some text to other text which I
can do fine in the visitor functions.
What I want to do is that I want to be able to use a cross reference in
my input text. So something like
Hello everyone, This text will be processed in my plugin. But This
cross reference should still work. :ref:`my-reference-label`
Will be processed. I can detect the :ref:`my-reference-label` in my extension but I cannot find anywhere in how I can turn this into an appropiate link to insert into the body,
so for html that would become a link tag to the appropriate location and for latex it would become a hyperref.
Maybe I am missing something really simple but I can't find it all.
In the sample extension: http://www.sphinx-doc.org/en/master/extdev/tutorial.html#the-event-handlers.
A URL is manually constructured but obviously I don't know at all where the ref is in my case.
Also that would only work for HTML output and not for latex or others.
Any help is appreciated.
--
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...