Path: csiph.com!news.mixmin.net!aioe.org!bofh.it!news.nic.it!robomod
From: "Rebecca N. Palmer" <rebecca_palmer@zoho.com>
Newsgroups: linux.debian.maint.python
Subject: Documentation path and Python 2->3
Date: Thu, 18 Jul 2019 09:40:01 +0200
Message-ID: <yl9bb-8cS-1@gated-at.bofh.it>
Old-Return-Path: <rebecca_palmer@zoho.com>
Domainkey-Signature: a=rsa-sha1; q=dns; c=nofws; s=zapps768; d=zoho.com; h=to:from:subject:message-id:date:user-agent:mime-version:content-type; b=NSFl9EXejBWAH8d3i/68nZXZHfhXD4zR53mRXb667omqLJQGHg/5lfa3r2TwwpHcE8k4qxKb+wqX pWrJP+V1GMElDhC3eupQth25YGtQYhNGVakHkjrFGjndSHSNx3or
User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:60.0) Gecko/20100101 Thunderbird/60.8.0
MIME-Version: 1.0
Content-Type: text/plain; charset=utf-8; format=flowed
Content-Language: en-US
Content-Transfer-Encoding: 7bit
Approved: robomod@news.nic.it
Lines: 38
Organization: linux.* mail to news gateway
Sender: robomod@news.nic.it
Xref: csiph.com linux.debian.maint.python:11486

(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