search

Quansight-Labs / intersphinx_registry

https://pypi.org/project/intersphinx_registry
MIT License
9 stars 4 forks source link

Look into https://sphobjinv.readthedocs.io/ to merge multiple obj.inv ? #2

Open Carreau opened 2 months ago

bskinn commented 2 months ago

<wave> sphobjinv author here.

You could definitely use the sphobjinv API to merge multiple objects.inv into a single master inventory. The main thing to watch out for would be duplicate object names within a given domain+role namespace, since intersphinx doesn't do any disambiguation there... I think it just grabs the first matching entry it finds in the inventory.

It also wouldn't be useful to merge inventories from docsets that live at different base URLs, because intersphinx has a one-to-one association of objects.inv --> base URL. E.g., you wouldn't be able to use an objects.inv that merges the matplotlib and numpy docs.

Carreau commented 2 months ago
sphobjinv author here.

:heart:

You could definitely use the sphobjinv API to merge multiple objects.inv into a single master inventory. The main thing to watch out for would be duplicate object names within a given domain+role namespace, since intersphinx doesn't do any disambiguation there... I think it just grabs the first matching entry it finds in the inventory.

Yeah, I would have checked that all objects in the inventory do correspond to the package that publish the obj.inv

It also wouldn't be useful to merge inventories from docsets that live at different base URLs, because intersphinx has a one-to-one association of objects.inv --> base URL. E.g., you wouldn't be able to use an objects.inv that merges the matplotlib and numpy docs.

I was wondering about that and if we could rewrite the obj.inv to have full-urls instead of just the path.

I think this might be usefull though for things like numpy which websites is actually 2 sphinx builds, under different baseurl, so this could allow to have a single obj.inv for numpy, numpy-tutorial , same for scipy/scipy-devdocs.

bskinn commented 2 months ago

I was wondering about that and if we could rewrite the obj.inv to have full-urls instead of just the path.

It might work. The base URL is defined in intersphinx_mapping, and each inventory object then defines its own URI that's relative to that base URL. As far as I know, they're just concatenated to form the links in the rendered docs.

So, in theory, if you put an empty string for the base URL in intersphinx_mapping and include complete URLs (with scheme) as the uri fields in the objects.inv, it seems like it should work. But, if intersphinx uses that base URL anywhere else, or if it chokes on that empty string, it'll blow up.

Wouldn't hurt anything to run the experiment.

I think this might be usefull though for things like numpy which websites is actually 2 sphinx builds

Yeah, I figured that was the use-case you were picturing for this. Seems like it should work pretty smoothly for any set of sites that has a common base URL.