Wrap annotations with an html tag

[pfebrer]

Is it possible to wrap the annotation in some custom html tag?

I want to style the whole annotation to have the same background, but looking at the generated HTML it looks like an unnecessarily daunting task, with parenthesis and commas being just text and merged with the description text. This is Union[str, int]:

which results in background changes for [, ] and , making it very hard to read:

[gaborbernat]

PR welcome.

[pfebrer]

I would like to, but I don't know where to begin 😅

[pfebrer]

Should I be able to acheive this with typehints_formatter ?

[hoodmane]

I did a similar thing in sphinx-js. It's largely a limitation of restructured text / the way that sphinx works. What I did is

1. make a role which takes escaped rst, unescapes it, renders it into a docutils tree, and then wraps it with css span
   https://github.com/pyodide/sphinx-js-fork/blob/master/sphinx_js/directives.py#L55-L66
2. when we render the type, escape your original rst and wrap it with the css anchor role:
   https://github.com/pyodide/sphinx-js-fork/blob/master/sphinx_js/renderers.py#L432

I'm not sure if this is the best way, it feels a bit hacky but this was the best way I could figure out to make it work.

You can see the result here: all the types have this css wrapper. If you adjust the css for .sphinx_js-type you can add your box:
https://pyodide.org/en/latest/usage/api/js-api.html#pyodide

[pfebrer]

Thanks for the comments!

After some investigation I realized that as you point out I have to go too deep into sphinx to implement this and I think it's not worth it for me to spend time on. I thought it would be easier, I didn't know the inner workings of sphinx were so complicated 😅

[hoodmane]

I can try to do this when I get around to it. I think it's a very helpful feature.

[gaborbernat]

Agreed 👍

[pfebrer]

By the way I wonder if it would make more sense to contribute this to sphinx.ext.autodoc. I don't really know exactly what sphinx.ext.autodoc wants to support in terms of typehints, I'm new to this sphinx typehint world. But it seems that its support for typehints is quite good, no? Maybe it wasn't like this in the past (?)

[gaborbernat]

Their style of choice is different. Both packages can coexist.

[hoodmane]

Resolved by #397.