Allow links to arbitrary intersphinx references

[adiroiban]

I think that pydoctor, at least with epydoc syntax only supports links from pydoctor to sphinx for API objects.

https://pydoctor.readthedocs.io/en/latest/sphinx-integration.html#linking-from-pydoctor-to-external-api-docs

There is no support for generic object reference

In Sphinx the syntax is

:external+otherbook:doc:`installation`

https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html

---

In pydoctor, the external search is implicit L{datetime.datetime} will search all external inventories for datetime.datetime reference.

We might want to implement something like L{:external+otherbook:doc:installation} to keep it as close as possible to the sphinx format

[tristanlatr]

This is a hard one because our intersphinx inventory is absolutely not built with this in mind.

As a consequence, we don't have the "project name" which correspond to the inventory objects, because it's not necessary to lookup python objects. But to lookup narrative docs pages, we need to know on which project to look for, because all project will have a page named "install" or "quickstart", etc.

So this definitely needs more reflexion.

[tristanlatr]

The logic should be adjusted so that:

• The sphinx inventory support having several time the same python name if they belong to two different projects.
• When linking to a name that is defined in several project, the linker bails and suggest to use the new syntax with the project specification because the current link is ambiguous.
• All the entries (doc:, label:, etc) should be added to the project inventory as long as it does not override any defined python object, if it does simply print a message and ignore it.
• The --intersphinx argument syntax should be augmented so we may pass the project name alongside its url. Like : --intersphinx=pydoctor:https://pydoctor.readthedocs.io/en/latest/objects.inv
• The sphinx extension should be reviewed and potentially adjusted so pydoctor can link to the local sphinx pages automatically without the need to register another intersphinx url.
• This last point might require the feature Intersphinx from local folder #741

What do you think @adiroiban ?

[tristanlatr]

Also, to be compatible with sphinx, /objects.inv should be added automatically if missing.

[tristanlatr]

I’ll first add support for these kind of link to the restructured text markup only since it’s easier to implement with the docutils roles. Then for epytext we’ll need to get creative. The main issue being the fact that names in the intersphinx mapping can contains colons. So making the difference in between the meta information and the link target might be difficult since the meta informations can contain one, two or three columns in the sphinx world.

[tristanlatr]

I have an idea: what about introducing a new epytex markup R{} that would render the content using restructuredtext.
So these link would be rendered using R{:external+otherbook:doc:`installation`}

[adiroiban]

The --intersphinx argument syntax should be augmented so we may pass the project name alongside its url. Like : --intersphinx=pydoctor:https://pydoctor.readthedocs.io/en/latest/objects.inv

I think that the .inv file format includes the project name.

But it's ok to have it as --intersphinx=pydoctor:https://pydoctor.readthedocs.io/en/latest/objects.inv to allow for renaming the project.

---

Also, to be compatible with sphinx, /objects.inv should be added automatically if missing.

This would be nice.
I am not sure how this can be implemented.
You can have the inventory at https://docs.python.org/3/py-inv.bin or just https://docs.python.org/3/api-inventory... if you don't set an extension for the file.

---

Yes. Having #741 would be nice.

---

I have an idea: what about introducing a new epytex markup R{} that would render the content using restructuredtext.
So these link would be rendered using R{:external+otherbook:doc:installation}

Not sure if this is a good idea.
This will make RST a hard requirement for epydoc.

Just my quick feedback.

Thanks for working on pydoctor :)

[tristanlatr]

thanks for your inputs

Not sure if this is a good idea.
This will make RST a hard requirement for epydoc.

docutils is already a hard requirement for epytext. This would also fix some weaknesses of epytext like not being able to do tables or admonitions, but this can be implemented in a second phase.