Reference linking with generics

agjohnson commented 9 years ago

So Sphinx has the concept of aliasing reference links using the following syntax:

.. dn:class:: Foobar

:dn:cls:`LinkAlias<Foobar>`

This references the class object Foobar, but prints the text LinkAlias. This of course overlaps with the .NET signature syntax of:

.. dn:class:: Foobar<T>

* This is hacked to work, using link object T as a special case:
  :dn:cls:`Foobar<T>`

.. dn:class:: Foobar<TNode>

* This will fail to reference, because TNode is not a special case:
  :dn:cls:`Foobar<TNode>`
* The correct way to reference the later case is the very unappealing, but
  Sphinx Approved:
  :dn:cls:`Foobar\<TNode\>`

The question here is do we drop the ability to have aliased links in Sphinx on the .NET domain completely, and fix all cases of the generic type syntax?

For reference: https://github.com/rtfd/sphinxcontrib-dotnetdomain/blob/525fb4fe71c4a1299df017d3243989f756bc6a5e/sphinxcontrib/dotnetdomain.py#L425-L444

agjohnson commented 9 years ago

cc @danroth27

ericholscher commented 9 years ago

Looks like on MSDN they have a convention of using (T) instead of <T> in some places.

Example: https://msdn.microsoft.com/en-us/library/6sh2ey19(v=vs.110).aspx

agjohnson commented 9 years ago

Is that just a type in a normal argument list, or signature type declaration?

agjohnson commented 9 years ago

Maybe we provide some special syntax here?

* .NET Link with an alias:
  :dn:cls:`Alias<<Foobar>>`
* .NET Link with an alias to generic:
  :dn:cls:`Alias<<Foobar<T>>>`

agjohnson commented 9 years ago

This is closed with #29

readthedocs / sphinxcontrib-dotnetdomain

Reference linking with generics #19