intersphinx: Warn about serialization of ambiguous 'objects.inv' entries.

[jayaddison]

Feature or Bugfix

• Bugfix

Purpose

• Implements a suggestion from previous discussion here.

Detail

• At inventory-serialization-time, emit a warning-severity log message when two or more entries resolve to the same case-insensitive name and contain differing content.

Relates

• Relates to #12329 (where warnings were added at inventory-loading-time).

Edit: adjust description to reduce scope. Glossary items that collide case-insensitively despite referring to the same concept do continue to emit ambiguity warnings with these changes currently.

[jayaddison]

@chrisjsewell it's been a while since we discussed this one, and I haven't seen many (any?) more reports about duplicate intersphinx entries, but even so it does still seem valid to attempt to catch introduction of ambiguous definitions early.

There's one nitpick/caveat I've added about glossary entries that currently emit ambiguous entries; I think we could resolve that in future but I'll file a separate issue about that.

[jayaddison]

There's some time cost to reading more of the background/history here, but I think it could be valuable. While addressing a question on a separate thread, I've attempted to summarize some of that history: https://github.com/sphinx-doc/sphinx/issues/12861#issuecomment-2333768677

I'm not 100% certain about all of my findings -- but notably at least one project does genuinely define two distinct term names that compare equally iff they are converted to lowercase.

[jayaddison]

I'm on the fence about whether to close this or not. I do think it's good to avoid creation/hosting of ambiguous references in the first place.. and/or to at least be aware when those situations arise -- but there is also the chance that any additional warnings here would cause disruption.

[jayaddison]

I'm on the fence about whether to close this or not. I do think it's good to avoid creation/hosting of ambiguous references in the first place.. and/or to at least be aware when those situations arise -- but there is also the chance that any additional warnings here would cause disruption.

I think I'll close it; if anyone's interested in continuing this, please feel free to re-use the contents of this branch.