Intersphinx from local folder

[miloth]

Hi,

We have some privately hosted repos and docs. We are trying to link to those during our docs generation by using locally cloned versions. Yet, if this is in the config:

intersphinx = [
    "https://docs.python.org/3/objects.inv",
    ...
    "<LOCAL-REPO-DIR>/objects.inv",
]

pydoctor throws the following warning:

Failed to uncompress inventory from <LOCAL-REPO-DIR>

Is there a way to add references to local files, like with the intershinx-mapping option of sphinx:

intersphinx_mapping = {"<PACKAGE-NAME>": ("<DOCS-PRIVATE-URL>", "<LOCAL-REPO-DIR>/objects.inv")}

The path to the inv file could be absolute or relative, no real preference on what is more convenient.

Thanks!

[tristanlatr]

Hello @miloth,

There is currently no way to include local objects.inv file. But support for this could be relatively easy to add. Maybe adding an new option —intersphinx-file.

Looking at the file sphinx.py would be a good starting point.

[tristanlatr]

Better, we could simply add support for the file:// scheme.

[miloth]

Hi @tristanlatr, thanks for the response and the suggestions. I don't have hours available to allocate to this, but I will get back to it if I find some.

I don't know if the url file:// scheme will work, because the links in the compiled docs should point to the private URL where the dependency is hosted, not where the local objects.inv files are fetched for the intershpinx at docs compile.

[tristanlatr]

I don't know if the url file:// scheme will work, because the links in the compiled docs should point to the private URL where the dependency is hosted, not where the local objects.inv files are fetched for the intershpinx at docs compile.

I think the is a misunderstanding, I’m not proposing to generate links with the file:// scheme, but to use the file:// scheme in the intersphinx list configuration to differentiate local and remote objects.inv. But, thinking about it twice: it’s probably misguided because the file:// scheme theoretically also support providing a remote host to fetch the file from…

Any opinion about this @glyph ?

[glyph]

But, thinking about it twice: it’s probably misguided because the file:// scheme theoretically also support providing a remote host to fetch the file from…

Any opinion about this @glyph ?

technically speaking, file://host/.../ is valid, but the only practical way to interpret this is a UNC pathname, which is local…enough, I guess. I think using this URI scheme is a good way to disambiguate, and if you want to be careful to not open up an esoteric minor vulnerability that could cause a user's machine to reach out to a surprising UNC host, you can just enforce that the host of the file URI is '' before passing it on.

[tristanlatr]

Easier: if the string doesn’t contain  :// then it’s treated like a file. This is how Sphinx handles it.