Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]

Groups > linux.debian.maint.python > #10839

Bug#906949: Clarify documentation location in a Python2-less distribution

Cross-posted to 3 groups.

Show key headers only | View raw

Package: debian-policy
X-Debbugs-CC: debhelper-devel@lists.alioth.debian.org, debian-python@lists.debian.org

Hi!

[ Promised follow up to the Python BoF at DebConf ]

For historical reasons, Python 2 modules are packaged as python-foo while 
Python 3 modules are python3-foo. Documentation was originally only for 
Python 2 modules (but in any event is normally interpreter independent) and 
so is found in python-foo-doc packages.

Policy §12.3 (from version 3.9.7) recommends that documentation from the 
python-foo-doc package be installed in /usr/share/doc/python-foo/ and not in 
/usr/share/doc/python-foo-doc/. From debhelper 10.8, dh_installdocs now does 
this automatically. In buster, documentation in python-foo-doc is slowly 
drifting over to /usr/share/doc/python-foo as packages are updated to compat 
11.

After the release of buster, we can expect to see Python 2 modules being 
dropped from the archive. Policy §12.3 and debhelper's interpretation of 
"main package" will suddenly cause documentation move from 
/usr/share/doc/python-foo to /usr/share/doc/python3-foo. This seems somewhat 
perverse for the user, will require changes to packaging (doc-base, rules, 
links) and perhaps code patches to packages that can display their own 
documentation.

The BoF felt it made sense to adopt a standardised approach and to have this 
sorted prior to the buster release in case any tooling changes are required. 
This affects about 700 packages.

We seek some input from the policy and debhelper people in defining what this 
approach should be. The following options exist:

a) do nothing: allow all the documentation to drift slowly over to 
/usr/share/doc/python3-foo, probably releasing buster and bullseye with a bit 
of a mess of locations: /usr/share/doc/python-foo-doc, 
/usr/share/doc/python-foo, /usr/share/doc/python3-foo. This seems pretty bad 
for our users.

b) keep using /usr/share/doc/python-foo: do we stick with 
/usr/share/doc/python-foo as a version-independent path even though no such 
package exists once the Python 2 package is gone? (I think there are 
currently no /usr/share/doc/ paths that don't match /usr/share/doc/$package)

c) coordinated move: do we try to switch the "main package" to the Python 3 
variant now so that all documentation moves over to 
/usr/share/doc/python3-foo? Churning d/control on 700 packages doesn't seem 
fun, so perhaps debhelper can assist?

d) revert to /usr/share/doc/python-foo-doc: do we ignore policy's 
recommendation, overriding (or changing) dh_installdocs? While 
/usr/share/doc/main-package is only a recommendation in policy, 700 
python-foo-doc packages deliberately ignoring it seems wrong.

Thanks in advance for your suggestions!

Stuart
(on behalf of the Python BoF at DebConf18)

-- 
Stuart Prescott    http://www.nanonanonano.net/   stuart@nanonanonano.net
Debian Developer   http://www.debian.org/         stuart@debian.org
GPG fingerprint    90E2 D2C1 AD14 6A1B 7EBB 891D BBC1 7EBB 1396 F2F7

Back to linux.debian.maint.python | Previous | Next — Next in thread | Find similar | Unroll thread

Thread

Bug#906949: Clarify documentation location in a Python2-less distribution Stuart Prescott <stuart@debian.org> - 2018-08-22 17:30 +0200
  Bug#906949: Clarify documentation location in a Python2-less distribution Simon McVittie <smcv@debian.org> - 2018-08-22 17:50 +0200

csiph-web