Path: csiph.com!weretis.net!feeder4.news.weretis.net!news.mixmin.net!aioe.org!bofh.it!news.nic.it!robomod
From: Scott Kitterman <debian@kitterman.com>
Newsgroups: linux.debian.maint.python
Subject: Re: Consistent location for library documentation
Date: Sat, 03 Mar 2018 11:00:02 +0100
Message-ID: <vpc7o-y4-27@gated-at.bofh.it>
References: <u3JOV-2x5-3@gated-at.bofh.it> <vpbEl-f5-1@gated-at.bofh.it>
Old-Return-Path: <debian@kitterman.com>
User-Agent: KMail/4.13.3 (Linux/3.13.0-139-generic; KDE/4.13.3; x86_64; ; )
MIME-Version: 1.0
Content-Transfer-Encoding: quoted-printable
Content-Type: text/plain; charset="utf-8"
Approved: robomod@news.nic.it
Lines: 119
Organization: linux.* mail to news gateway
Sender: robomod@news.nic.it
Xref: csiph.com linux.debian.maint.python:10222

Look at Debian Policy, section 12.3 Additional Documentation.  The answ=
er is=20
there.

Scott K

On Saturday, March 03, 2018 09:25:20 AM Christopher Hoskin wrote:
> Dear Ben,
>=20
> Did you get an answer to this?
>=20
> I've just noticed a change in behavior of dh_installdocs between
> debhelper compat 10 and 11. With compat 10, documents listed in
> debian/python-<package>-doc.docs (e.g. build/html) would get installe=
d
> to /usr/share/doc/python-<package>-doc/ but with compat 11, they get
> installed to /usr/share/doc/python-<package>/.
>=20
> >From the dh_installdocs man page it appears dh_installdocs has some
>=20
> logic to auto-detect the main package, which can be overridden with
> the --doc-main-package option.
>=20
> I'd like to know if dh_installdocs' default is considered correct, or=

> if I should be overriding it?
>=20
> Thanks.
>=20
> Christopher
>=20
> On 16 July 2017 at 05:54, Ben Finney <bignose@debian.org> wrote:
> > Howdy all,
> >=20
> > Where is the best location for library documentation of a Debian Py=
thon
> > library package?
> >=20
> > Debian Policy =C2=A712.3 says:
> >     [=E2=80=A6] installing the documentation into the documentation=
 directory of
> >     the main package is preferred since it is independent of the
> >     packaging method and will be easier for users to find.
> >=20
> > This is clear enough where a library package =E2=80=98libfoo=E2=80=99=
 is the main
> > package. The documentation package =E2=80=98libfoo-doc=E2=80=99 can=
 install the
> > documentation to =E2=80=98/usr/share/doc/libfoo/=E2=80=99.
> >=20
> >=20
> > With the split in Python runtime systems, though, there is commonly=
 not
> > a single =E2=80=9Cmain package=E2=80=9D. Typically there are two, =E2=
=80=98python3-foo=E2=80=99 and
> > =E2=80=98python-foo=E2=80=99.
> >=20
> > The documentation package =E2=80=98python-foo-doc=E2=80=99 then has=
 no one obvious place
> > to install the documentation:
> >=20
> > * Installing to =E2=80=98/usr/share/doc/python-foo-doc/=E2=80=99 is=
 discouraged by the
> >=20
> >   above Policy section. I agree that is not necessarily an obvious =
place
> >   for a user to look for =E2=80=98python3-foo=E2=80=99 documentatio=
n.
> >=20
> > * Installing to =E2=80=98/usr/share/doc/python-foo/=E2=80=99 or
> >=20
> >   =E2=80=98/usr/share/doc/python3-foo/=E2=80=99 is incorrect if the=
 corresponding
> >   library package is not installed.
> >=20
> > Compounding this is the fact we are (rightly, IMO) moving toward Py=
thon
> > 3 as the primary runtime, and discouraging new Python 2 packages. I=
s
> > =E2=80=98python3-foo=E2=80=99 then the =E2=80=9Cmain package=E2=80=9D=
 by the Policy statement above?
> >=20
> > A symlink could be used, from =E2=80=98/usr/share/doc/libfoo-doc=E2=
=80=99 to
> > =E2=80=98/usr/share/doc/libfoo=E2=80=99. But that still runs into t=
he problem of *which*
> > package should be assumed.
> >=20
> > And if the documentation package *only* is installed, where should =
it
> > install its documentation and symlinks? How should this be done to =
allow
> > the library packages to later be installed without changing the
> > documentation location?
> >=20
> >=20
> > I have looked at various documentation and can't see good guidance =
for a
> > =E2=80=9Cone obvious way=E2=80=9D to resolve this.
> >=20
> > There is varying practice among packages, and anyway just because s=
ome
> > package does it a particular way doesn't mean I should copy that wi=
thout
> > knowing whether it's a good idea.
> >=20
> > What to do?
> >=20
> > --
> >=20
> >  \             =E2=80=9CI put contact lenses in my dog's eyes. They=
 had little |
> > =20
> >   `\   pictures of cats on them. Then I took one out and he ran aro=
und |
> >=20
> > _o__)                                      in circles.=E2=80=9D =E2=
=80=94Steven Wright |
> > Ben Finney