(Sorry if this has been discussed before: it's not obvious how to search
for it)
Policy 12.3 [0] states that documentation for $package should preferably
be packaged as $package-doc but still install to /usr/share/doc/$package
not /usr/share/doc/$package-doc. By default, debhelper implements this
as "if $package (or $package-dev) exists in the same source, install
$package-doc to /usr/share/doc/$package(-dev), otherwise install it to
/usr/share/doc/$package-doc" [1].
For Python packages, this means that python-$module-doc moves from
/usr/share/doc/python-$module to /usr/share/doc/python-$module-doc when
the Python 2 $module ceases to exist [2]. This may break links
(doc-base [3], users' local bookmarks, etc).
Should it instead move to /usr/share/doc/python3-$module? (And if so,
should the -doc package be renamed to python3-$module-doc? though that
implies a large[4] amount of binary-NEW processing...) Or stay in
/usr/share/doc/python-$module to not break links?
Should there be symlinks to the documentation in whichever of
/usr/share/doc/python3-$module, /usr/share/doc/python-$module-doc and
(if it exists) /usr/share/doc/python-$module don't contain the actual
documentation? This was suggested for the general
/usr/share/doc/$package-doc to /usr/share/doc/$package case in the
original Policy discussion [5], but didn't make into actual Policy.
[0]
https://www.debian.org/doc/debian-policy/ch-docs.html#additional-documentation
[1]
https://sources.debian.org/src/debhelper/12.2.2/lib/Debian/Debhelper/Dh_Lib.pm/#L2664
[2] e.g.
https://packages.debian.org/buster/all/python-django-doc/filelist ->
https://packages.debian.org/sid/all/python-django-doc/filelist
[3] https://bugs.debian.org/931652
[4] there are currently 661 python-$module-doc (and 19
python3-$module-doc, which appear to be new packages rather than renames)
[5] https://bugs.debian.org/106073
