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

Groups > linux.debian.bugs.dist > #914137 > unrolled thread

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

Back to article view | Back to linux.debian.bugs.dist

Contents

  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
    Bug#906949: Clarify documentation location in a Python2-less distribution Ian Jackson <ijackson@chiark.greenend.org.uk> - 2018-08-23 16:50 +0200
      Bug#906949: Clarify documentation location in a Python2-less distribution Simon McVittie <smcv@debian.org> - 2018-08-23 19:00 +0200
        Bug#906949: Clarify documentation location in a Python2-less distribution Ian Jackson <ijackson@chiark.greenend.org.uk> - 2018-08-23 20:20 +0200

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

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

[toc] | [next] | [standalone]

#914139

On Thu, 23 Aug 2018 at 01:20:44 +1000, Stuart Prescott wrote:
> 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.

In dbus-python I left the documentation in /usr/share/doc/python-dbus-doc
(overriding dh_installdocs), but put symlinks to it in
/usr/share/doc/python{,3}-dbus so that users can find it by following
the Policy-recommended route. Maybe that's a reasonable compromise?

    smcv

[toc] | [prev] | [next] | [standalone]

#914352

Stuart Prescott writes ("Bug#906949: Clarify documentation location in a Python2-less distribution"):
> 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)

This seems good to me.  You could offer a symlink.

There are two reasons for the standardised paths in /usr/share/doc:
 1. So that the user can find the right documentation.
 2. So that you avoid clashes with other packagkes.

Not moving the docs about assists 1.  As does providing a link
/usr/share/doc/python3-foo -> python-foo.

If there is no python[2] package then 2 is also served.


Alternatively, when dropping the python[2] package, move the docs but
leave a symlink the other way:
 /usr/share/doc/python-foo -> python3-foo


Both of these mean /usr/share/doc is a bit more cluttered, but people
will be able to find the thing they are looking for, and they will
minimise the impact of the `messiness' of the transition.

What do you think of that idea ?

Ian.

[toc] | [prev] | [next] | [standalone]

#914377

On Thu, 23 Aug 2018 at 15:43:06 +0100, Ian Jackson wrote:
> There are two reasons for the standardised paths in /usr/share/doc:
>  1. So that the user can find the right documentation.
>  2. So that you avoid clashes with other packagkes.
> 
> Not moving the docs about assists 1.  As does providing a link
> /usr/share/doc/python3-foo -> python-foo.

It would be non-Policy-compliant for python3-foo to have a symlink
/usr/share/doc/python3-foo -> python-foo unless it Depends on
python-foo (= ${binary:Version}), because python3-foo is required to
contain or provide a corresponding /usr/share/doc/python3-foo/copyright
and .../changelog.Debian.gz.

However, it would be wrong for python3-foo to depend on python-foo
or vice versa, because they are libraries for different interpreters
and do not really have any dependency relationship. That's why the
documentation is usually split out into python-foo-doc.deb.

> Alternatively, when dropping the python[2] package, move the docs but
> leave a symlink the other way:
>  /usr/share/doc/python-foo -> python3-foo

Similarly, you can't do that unless python3-foo Conflicts: python-foo,
which seems like overly-aggressive deprecation :-)

Symlinks *inside* the per-package documentation directory are OK though,
for example /usr/share/doc/python3-foo/html -> ../python-foo/html, or
perhaps more realistically
/usr/share/doc/python{,3}-foo/html -> ../python-foo-doc/html,
which is how this works in src:dbus-python for example.

    smcv

[toc] | [prev] | [next] | [standalone]

#914390

Simon McVittie writes ("Re: Bug#906949: Clarify documentation location in a Python2-less distribution"):
> On Thu, 23 Aug 2018 at 15:43:06 +0100, Ian Jackson wrote:
> > There are two reasons for the standardised paths in /usr/share/doc:
> >  1. So that the user can find the right documentation.
> >  2. So that you avoid clashes with other packagkes.
> > 
> > Not moving the docs about assists 1.  As does providing a link
> > /usr/share/doc/python3-foo -> python-foo.
> 
> It would be non-Policy-compliant for python3-foo to have a symlink
> /usr/share/doc/python3-foo -> python-foo unless it Depends on
> python-foo (= ${binary:Version}), because python3-foo is required to
> contain or provide a corresponding /usr/share/doc/python3-foo/copyright
> and .../changelog.Debian.gz.

I think you have misunderstood me.  I am suggesting that, when python2
package is dropped, the python3 package would ship both
  /usr/share/doc/python-foo
  /usr/share/doc/python3-foo
and one would be a symlink to the other.

There would have to be some care taken to make the upgrade smooth.

> Similarly, you can't do that unless python3-foo Conflicts: python-foo,
> which seems like overly-aggressive deprecation :-)

We would need to get around that, indeed.  By managing the link in
maintainer scripts.

> Symlinks *inside* the per-package documentation directory are OK though,
> for example /usr/share/doc/python3-foo/html -> ../python-foo/html, or
> perhaps more realistically
> /usr/share/doc/python{,3}-foo/html -> ../python-foo-doc/html,
> which is how this works in src:dbus-python for example.

That would be another possibility.

Ian.

-- 
Ian Jackson <ijackson@chiark.greenend.org.uk>   These opinions are my own.

If I emailed you from an address @fyvzl.net or @evade.org.uk, that is
a private address which bypasses my fierce spamfilter.

[toc] | [prev] | [standalone]

Back to top | Article view | linux.debian.bugs.dist

csiph-web