index directive and role emit deprecation warnings for python index-types

[tk0miya]

Feature or Bugfix

• Refactoring

Purpose

• python specific index-types are marked as deprecated in this commit: 3e9182550a (10years ago!)
• This emits deprecation warnings to remove them in future.

[shimizukawa]

LGTM for the diff.
My concern is that the official Python documentation uses a lot of module and object.

• object
• module

Python official documentation seems to take time to adapt to new writing style like pair: module; blabla.

[tk0miya]

@JulienPalard @cocoatomo We'd like to mark some python-specific index-types deprecated obviously (accurately it has already been marked as deprecated in our document). It does not mean they will be removed right away. It will be removed in Sphinx-5.0 (maybe 2 years later). It seems python-doc contains some index entries (see @shimizukawa 's comment). Do you have any opinions for this idea?

[JulienPalard]

@tk0miya Thanks for the heads up!

Would a proper fix looks like this python/cpython#18004?

If so, feel free to copy-past my seds to the page documenting this deprecation and how to fix it.

[JulienPalard]

@tk0miya have you looked at #6970 (comment)?

[tk0miya]

Sorry for the late response. I found problems on i18n with this deprecation. The python index-types are translated on index pages automatically via language configuration.

For example, .. index: builtin: len is translated to the pair of "組み込み関数" and "len" in Japanese document. On the other hand, .. index:: pair: builtin: len is not translated. So it is displayed as pair of "builtin" and "len" even in Japanese docs.

We need to resolve this before the deprecation. So I withdraw this proposal for a while.

Sorry for bothering you.

[codecov]

Codecov Report

❗ No coverage uploaded for pull request base (master@1fc4e8c). Click here to learn what that means.
The diff coverage is n/a.

[AA-Turner]

Resolved by #11412.