External references are not resolved in TOC tree sidebar

[mwoehlke]

Let's say I have a document like:

Title
=====

:doc:`some-page`
----------------

This is a section (but not the page title)
whose name is the same as,
and incidentally also a link to,
another piece of documentation.
I used ``:doc:`` here,
but at least ``:ref:``
|--| very possibly everything that uses ``XRefRole``
and the delayed resolution thereof |--|
shows the same problem.

In the body of the document, the reference title is resolved as expected. (Let's say for example that the document title is "Describe Some Page Here". Then, in the body, the heading appears as "Describe Some Page Here".) However, in the sidebar TOC, the heading appears as "some-page". That is, the TOC uses the raw text of the reference, rather than the resolved text. Besides looking ugly, this is confusing and almost certainly not intended, as it means that the heading text in the TOC and the document body are different.

On consideration, I suspect the problem is that the TOC is using astext on XRefRole nodes, which drops the external reference bits before they can be resolved. This may be a tricky fix, as I suspect that, besides tweaking the TOC to allowed delayed text resolution (which in itself may be non-trivial), all of StandardDomain.resolve_xref may need to sprout a mode to resolve text but not actually emit a reference (since in the TOC case, the reference we want is to the section that used the external reference in its title, and not what the external reference actually references).

This should be reproducible with the following index.rst::

Hello, World
============

:doc:`index`
------------

(Verified by making a comparable change to the index.rst of a sphinx-quickstart project.)