Improve role slices in names
In this case, the
~ slice becomes nice (e.g.
:ref:`~foo.bar.baz.Qux.quux` only displays
quux() in the document), but this incurs a loss in readability if it slices into a separate class: the document author probably does not want the fully qualified namespace (for verbosity reasons), but having more than just the method name would be nice, for instance to have the class name as well.
I propose that the
~ syntax be extended with an index, which would give the (maximum) number of items displayed from the end:
~2 would display the last two items of the chain instead of only the last one.
With the dotted path above, you would get:
~foo.bar.baz.Qux.quux outputs quux() 1~foo.bar.baz.Qux.quux outputs quux() 2~foo.bar.baz.Qux.quux outputs Qux.quux() 3~foo.bar.baz.Qux.quux outputs baz.Qux.quux() 4~foo.bar.baz.Qux.quux outputs bar.baz.Qux.quux() 5~foo.bar.baz.Qux.quux outputs foo.bar.baz.Qux.quux()