Cross reference syntaxes not working with .NET domain links

[danroth27]

According to the Sphinx docs cross referencing syntax should work with domain links.

In the ASP.NET docs if I have this:

:dn:iface:`Microsoft.Extensions.Configuration.IConfiguration`

It renders a link like this:

But if I have this:

:dn:iface:`IConfiguration <Microsoft.Extensions.Configuration.IConfiguration>`

It gets rendered incorrectly like this without a link:

I also tried the ~ syntax, like this:

:dn:iface:`~Microsoft.Extensions.Configuration.IConfiguration`

But that didn't work either:

[danroth27]

@agjohnson This issue makes using the domain links really verbose in prose.

[agjohnson]

I believe this is due to the generic Foo<T> syntax, in references, we have removed Sphinx's named linking in order to support this syntax. An option here might be to manually escape the generic brackets when linking, though this might be cumbersome for authoring. We could also go against Sphinx's standard linking and provide another syntax here Named <<Target>> for instance.

Any thoughts here?

[danroth27]

Could we use the presence of whitespace to disambiguate? It looks like the rst syntax requires whitespace between the text and the link. I.e. foo <http://bar> works but foo<http://bar> doesn't. While technically C# allows whitespace between the type name and the angle brackets, in practice no one ever does that.

[danroth27]

It would also be super nice to support the ~ syntax. I would even say that's higher priority than getting the angle bracket syntax to work.

[agjohnson]

Ah yes, this is also a per-domain syntax that we'd have to handle in this domain. I've created #48 to address this feature.

[agjohnson]

~ prefix parsing was moved to #48, but forgot to mention that here.

I think handling this with a space might work, I don't know if this needs to handle nested references. It would be helpful if the parameter and return type parsing used this syntax to be able to build up nested references. For now, rtfd/sphinx-autoapi#66 gets around this by using this syntax:

Foo<Foo`1>{Bar<Bar`1>{TUser}}

This would be parsed by the domain to output the text Foo<Bar<TUser>>, where the elements link to Foo1andBar1, respectively.

Given space syntax, this could be parsed out as:

Foo<Bar<TUser> <Bar`1>> <Foo`1>

Hopefully no one ever needs to write that by hand.