-
-
Notifications
You must be signed in to change notification settings - Fork 2.1k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Intersphinx delegation to domains #8929
base: master
Are you sure you want to change the base?
Intersphinx delegation to domains #8929
Conversation
345e37f
to
aab40ea
Compare
Rebased to resolve conflicts. @tk0miya, do you by chance have time to review this before we get too close to the v4 release? |
Oh, sorry. I overlooked your PR at all. I completely agree with you. It's difficult to resolve cross-references only on the intersphinx module and common inventory data structure. So the resolution process should be passed to the domains. In my thought, it is better to export the whole of the env object (or the whole of the domain object) as an inventory database and import it as a real env (or domain) object on intersphinx. I think it's similar to this PR, but no new methods are needed. What do you think?
|
That would be delightfully simply, though I think we would still need domain-specific methods for the loading. The inventory may be generated by an old version, so As for lookup: the current intersphinx lookup does some extra tricks, like splitting of an inventory name and perform targeted lookup, or when multiple inventories have the same entry, then disambiguate it in a deterministic way. |
aab40ea
to
af5828f
Compare
1754c28
to
991f63d
Compare
Co-authored-by: Bénédikt Tran <10796600+picnixz@users.noreply.github.com>
Only add method to obj types if it's not there already.
991f63d
to
99cbdcd
Compare
Feature or Bugfix
Purpose
Currently, Intersphinx is performing lookups in inventories purely by string comparison. Unfortunately this does not work in general. For C and especially C++ more complex processing needs to be done.
As an overall goal for Intersphinx: provide cross-referencing to external projects as if those projects were merely a part of the current project. In order to do this I believe Intersphinx must delegate most processing of inventories and lookup to the domains. This means both a new inventory format is needed and changes to lookup. This PR tries to address the latter. See the bottom for notes on the inventory format.
Detail
sphinx.util.inventory.InventoryItemSet
. This class is private for Intersphinx.initial_intersphinx_inventory
. This mirrors the ordinary domain storage throughinitial_data
.intersphinx_add_entries_v2()
, where the domain stores in the given domain storage. Thev2
in the name refers to the current version ofobjects.inv
(the v1 is converted to v2).missing-reference
event it will use two new domain methodsintersphinx_resolve_xref
. The previously filled domain storage is given here as well.sphinx.util.inventory.InventoryItemSet
which must be returned (the domains doesn't know that it is this class, just some arbitrary data that it got from Intersphinx earlier). Intersphinx will then perform disambiguation between duplicates across the inventories, and create the resulting nodes.The old lookup code in
intersphinx.py
is now the default implementation in theDomain
base class for backwards compatibility. The domain-specific things forstd
andpy
have been spliced out (though in a slightly haxy manner).As a kind of proof-of-concept I have implemented custom handling in the C domain, where it reuses the ordinary symbol tables classes and lookup procedures. A test for lookup in relation to anonymous types illustrates that more lookups will work with this implementation.
Relates
Next steps
We should make a new inventory format where domains can store symbols in whichever format they like: https://github.com/orgs/sphinx-doc/discussions/12204