Fix #3351: intersphinx does not refers context

[tk0miya]

refs: #3351

I added a new interface Domain.get_full_qualified_name() to get the full qualified name from the node.
It allows to refer a target using context (e.g. py:module).

• Implement get_full_qualified_name() for other domains => Implement get_full_qualified_name() to C, C++, JavaScript and reST domains #3630
• Add doc about get_full_qualified_name()
• Add more test cases

[bitprophet]

A couple random suggestions:

• Given the implemented behavior is backwards compatible (the fully-qualified name is only added to the to_try list if it's non-empty), I'd argue there is no need to implement it for all other domains before merging; that could be left for future PRs from interested users.
• I wonder if it's possible to simply reuse the machinery that implements the 'find it anywhere' behavior from py:obj, i.e. the code that knows .ClassName can refer to anything called ClassName within the current project, regardless of module scope.
  • This is partly because I'm not 100% sure the current code will work right; when I apply it to an intersphinx reference, it would attempt to look up the name as if it was defined in the referencing module and class instead of the module and class it truly lives in.
  • So for example, referencing remote.project.FooClass inside a docstring from local.project.BarClass would try to add the name local.project.BarClass.FooClass to the lookup list...which I don't think would exist in the inventory for remote?

[tk0miya]

Now I rebased to master HEAD. Unfortunately, I don't have enough time to improve this to all of domains. so I'll do that in future version (@bitprophet Thank you for advice, I've overlooked your comment longer...).

@shimizukawa could you review this please? This adds a new interface to Domain class. So it should be reviewed before merging.

[tk0miya]

So for example, referencing remote.project.FooClass inside a docstring from local.project.BarClass would try to add the name local.project.BarClass.FooClass to the lookup list...which I don't think would exist in the inventory for remote?

@bitprophet Did you mean like following case?

.. py:module:: local.project

.. py:class:: BarClass

   This class refers :py:class:`remote.project.FooClass`.

In this case, intersphinx tries to search both FooClass and local.project.BarClass.remote.project.FooClass from remote inventories (after this PR).

Surely, the next case searches both FooClass and local.project.BarClass.FooClass. I think this is correct behavior of intersphinx.

.. py:module:: local.project

.. py:class:: BarClass

   This class refers :py:class:`FooClass`.

[bitprophet]

In this case, intersphinx tries to search both FooClass and local.project.BarClass.remote.project.FooClass from remote inventories (after this PR).

If that's the case then I misunderstood something, I thought it was only going to search for the fully-qualified local.project.BarClass.remote.project.FooClass. So, I'll wait & see if this gets merged & try it out. Thanks :)

[tk0miya]

Ah, sorry. my explanation was wrong.
Both remote.project.FooClass and local.project.BarClass.remote.project.FooClass are correct.
With this PR, intersphinx tries to search using both original keyword and full qualified one.

[shimizukawa]

LGTM!

I haven't seen generated doc, but new API should be described by autodoc, right?

[tk0miya]

Thank you for reviewing.
I will merge this after discussion in #3630 is finished.