[UX] Sphinx extension?

[webknjaz]

Hi, I just discovered this project by accident. I have a few toys in this space as well (https://webknjaz.github.io/intersphinx-untangled/ and https://pypi.org/p/sphinxcontrib-towncrier, to name a few).

I saw that the suggested usage method is importing the library and calling it in conf.py. I believe, however, that there's a more elegant way to make the UX feel more native to Sphinx.

It should be possible to implement a Sphinx extension interface that would just be added to the list of extensions in conf.py. It would be able to dynamically augment or replace intersphinx_mapping. And any configuration parameters could be top-level declarative vars in conf.py.

Have you considered doing this? I can give pointers and maybe even contribute some patches, if you're open to it.

[Carreau]

Yes, but I also want to have it in a more declarative form, so my hope is to fold that into https://github.com/Carreau/sphinx_toml – which I'm also working on.

Some of the off-github discussion I had ended up with us deciding to do the minimal to – for now – avoid the discussions related to what are the configuration options of an extensions.

You can see both this (and sphinx_toml) as experiments on how I'd like sphinx to behave natively in the end.

Also I think a sphinx extension could be yet another package, so we decouple the sphinx extension from the registry itself ?

Finally I wanted to make something like https://webknjaz.github.io/intersphinx-untangled/, but maybe learn javascript and have something search all entries ? I think we could use something like https://blog.cloudflare.com/sqlite-in-durable-objects/ to do that.

In then end feel free to suggest modifications; but I'd like to keep this as a minimal registry if possible. Already I find the 'lookup' to be an the edge of too much,

[webknjaz]

Also I think a sphinx extension could be yet another package, so we decouple the sphinx extension from the registry itself ?

Yep, fair enough, if that's the declared goal. Might be useful to spell out the scope in README, perhaps. It wasn't immediately obvious to me. A separate extension interface would be just a few lines of code.

Though, I see that the problem here is that the list is hardcoded. And making that wrapper project disconnected just feels irrational, given how much it'd be coupled. Hence, #56 — with that, it'd make more sense if there was an ecosystem'ish framework that would allow many separately installable Python dists to ship their own lists while relying on the same loader logic. Those projects would be composable through a common extension capable of autoloading (and merging?) those lists.
Perhaps, I need to experiment with this idea too…

Finally I wanted to make something like webknjaz.github.io/intersphinx-untangled, but maybe learn javascript and have something search all entries ? I think we could use something like blog.cloudflare.com/sqlite-in-durable-objects to do that.

Yeah, I'd hoped to stick some JS into intersphinx-untangled, but never found the time so it remains a dream :) There are a few web pages that are pretty large and can cause your browser tab to crash, so this is not just a nice to have but a UX necessity.

Too bad, I never had time to go past prototyping the idea and occasionally add new URLs to the config.

[Carreau]

I don't have objection to change the json file format, like if it's [project_name, url, list_of-tags], for example; this way this only hold data and minimal code, but it's a preference.

Main idea is that we don't have to "think" about wether we break API or compatibility when there is a URL/tag whatever update. That's it. But I can be convinced of otherwise.