Open adiroiban opened 2 years ago
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.
The logic should be adjusted so that:
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.--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
What do you think @adiroiban ?
Also, to be compatible with sphinx, /objects.inv
should be added automatically if missing.
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.
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`}
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 :)
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.
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
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 fordatetime.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