Custom Directive: how to correctly create reference to a class

[Nic30]

Basicaly I am trying to generate reference element to a class.

I am able to get a class object in `Directive.run()` which I want to reference in documentation.
Currently I am using `sphinx.util.typing.stringify` to get a string and then returning `docutils.nodes.Text`

I would like to create href in html documentation which redirects the browser to the type definition.

I guess I should use https://www.sphinx-doc.org/en/master/extdev/nodes.html#sphinx.addnodes.pending_xref

But I am not sure how or if it is a good idea. I can always craft the link manually as shown in https://www.sphinx-doc.org/en/master/development/tutorials/todo.html
Is there a better way?

I guess that the apidoc or other extensions needs to have function just for this but I just can't see it.

Any hit appreciated.

https://github.com/Nic30/sphinx-hwt/blob/master/sphinx_hwt/directive_params.py#L80

[Komiya Takeshi]

Hi,

Bingo! Sphinx uses the pending_xref nodes to realize the
cross-reference feature.

Please try to make a node that refers python class like this:

```
node = sphinx.addnodes.pending_xref(refdomain='py', reftype='class',
reftarget='stringio.StringIO')
node += nodes.Text('stringio.StringIO)
```

The pending_xref node should have three attributes:

* refdomain: domain of the reference. For python objects, please set 'py'.
* reftype: type of the python object.
* reftarget: name of the python object.

All you should do is only generating pending_xref node. It will be
converted to a cross-reference automatically on the latter step of
Sphinx.
Please try this in your code.

Thanks,
Takeshi KOMIYA

2020年12月10日(木) 5:54 Nic30 <nic30o...@gmail.com>:

> --
> You received this message because you are subscribed to the Google Groups "sphinx-users" group.
> To unsubscribe from this group and stop receiving emails from it, send an email to sphinx-users...@googlegroups.com.
> To view this discussion on the web visit https://groups.google.com/d/msgid/sphinx-users/f5079d3e-14c5-4966-b33f-d7bc94973b98n%40googlegroups.com.

[Nic30original]

Nice, that was the answer what I was hoping for.
I tried it before, but I did it in Element visit_html which resulted in

```
Exception occurred:
  File
"/usr/local/lib/python3.8/dist-packages/sphinx/writers/html5.py", line
793, in unknown_visit
    raise NotImplementedError('Unknown node: ' + node.__class__.__name__)
NotImplementedError: Unknown node: pending_xref
```

If I use pending_xref in Directive it works.

https://github.com/Nic30/sphinx-hwt/commit/ba360c63f91d776cc07962021d3368b60dd405c7#diff-6369c7879f44cbaf51bfd17223507b52dfed6646cefcac2bacd89bba46a2070bR197
<https://github.com/Nic30/sphinx-hwt/commit/ba360c63f91d776cc07962021d3368b60dd405c7#diff-6369c7879f44cbaf51bfd17223507b52dfed6646cefcac2bacd89bba46a2070bR197>

You can see the result on
https://hwtlib.readthedocs.io/en/latest/hwtLib.amba.axi_comp.lsu.html#module-hwtLib.amba.axi_comp.lsu.read_aggregator
<https://hwtlib.readthedocs.io/en/latest/hwtLib.amba.axi_comp.lsu.html#module-hwtLib.amba.axi_comp.lsu.read_aggregator>


Thanks.

[Komiya Takeshi]

I guess you used pending_xref nodes after the reading phase. They are
generated during the reading phase and converted into the reference
nodes on the resolving phase. As a result, writer components don't
handle them.

Thanks,
Takeshi KOMIYA

2020年12月12日(土) 23:26 Nic30original <nic30o...@gmail.com>:

> To view this discussion on the web visit https://groups.google.com/d/msgid/sphinx-users/4924cb01-25c3-84db-ba4e-9e6a50346e6a%40gmail.com.