Path: csiph.com!aioe.org!bofh.it!news.nic.it!robomod From: Christopher Hoskin Newsgroups: linux.debian.maint.python Subject: Re: Consistent location for library documentation Date: Sat, 03 Mar 2018 10:30:01 +0100 Message-ID: References: X-Mailbox-Line: From debian-python-request@lists.debian.org Sat Mar 3 09:25:47 2018 Old-Return-Path: X-Amavis-Spam-Status: No, score=-6.519 tagged_above=-10000 required=5.3 tests=[BAYES_00=-2, FREEMAIL_FORGED_FROMDOMAIN=0.25, FREEMAIL_FROM=0.001, HEADER_FROM_DIFFERENT_DOMAINS=0.25, LDO_WHITELIST=-5, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H3=-0.01, RCVD_IN_MSPIKE_WL=-0.01] autolearn=ham autolearn_force=no X-Policyd-Weight: DYN_NJABL=SKIP(0) NOT_IN_SBL_XBL_SPAMHAUS=-1.5 NOT_IN_BL_NJABL=-1.5 CL_IP_EQ_HELO_IP=-2 (check from: .gmail. - helo: .mail-qk0-f177.google. - helo-domain: .google.) FROM/MX_MATCHES_HELO(DOMAIN)=-2; rate: -7 X-Google-Dkim-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:mime-version:in-reply-to:references:from:date :message-id:subject:to:cc:content-transfer-encoding; bh=4HQySfrD6FK2DgWh+6YHzap8bJqBWfgbpU+yXT0ywfA=; b=Uip/qh1Pgyy/txDqvZ99Q1k7smsmLmO7Zd3RbiJZAzWssuGYsCPvmKRLBwjWPKfz7+ RDTkSdEAi37DhatD7UKLgH8coh9WNLUzelu5o5LU+TZeglcxExZerw9dwUbrUHyZHt4H 5K/6SLH0pfrL+WlbBcEY/irPWQvBcHEB+aH2l21MFDdQRb+eAe0ei7t1vJFE1ZLeUyss V52NRvj7aVgzzQltp4Y90VXft48WAJS1Ak54u1IL4vTRkU3xab+Q3eoGG36kIF4zRzan nwuRIOSVIQdyFyyRManKAB7kxkvxaO2pZXGBCrDKSMvusQPVpm8TgWB8sBroPjaeLtEq AEYQ== X-Gm-Message-State: AElRT7FCtJ6swsxBZm4UADxX09sYE1N1inR9jPVywQ95RYubeChZBZ6s 6yqtzu3PXON/XRRJl24OYDGJtSmET00= X-Google-SMTP-Source: AG47ELvx/tciMcLTZ9oGgqMCBKq8GuecrxX8oPrTY9CRXh9Dtu30BvlydLckWHieNLGZPzzgBkyjCA== X-Received: by 10.55.139.193 with SMTP id n184mr11702555qkd.299.1520069121713; Sat, 03 Mar 2018 01:25:21 -0800 (PST) X-Received: by 10.200.112.91 with SMTP id y27mr12468611qtm.295.1520069120978; Sat, 03 Mar 2018 01:25:20 -0800 (PST) MIME-Version: 1.0 X-Gmail-Original-Message-ID: Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: quoted-printable X-Mailing-List: archive/latest/15616 List-ID: List-URL: List-Archive: https://lists.debian.org/msgid-search/CAEjvcd9CdJK1-0i-xcqHfWFJMNhSpm0361Pgi07RQwjeyXSSBQ@mail.gmail.com Approved: robomod@news.nic.it Lines: 94 Organization: linux.* mail to news gateway Sender: robomod@news.nic.it X-Original-Cc: debian-python@lists.debian.org X-Original-Date: Sat, 3 Mar 2018 09:25:20 +0000 X-Original-Message-ID: X-Original-References: <85zic56kxk.fsf@benfinney.id.au> Xref: csiph.com linux.debian.maint.python:10221 Dear Ben, Did you get an answer to this? 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--doc.docs (e.g. build/html) would get installed to /usr/share/doc/python--doc/ but with compat 11, they get installed to /usr/share/doc/python-/. >From the dh_installdocs man page it appears dh_installdocs has some logic to auto-detect the main package, which can be overridden with the --doc-main-package option. I'd like to know if dh_installdocs' default is considered correct, or if I should be overriding it? Thanks. Christopher On 16 July 2017 at 05:54, Ben Finney wrote: > Howdy all, > > Where is the best location for library documentation of a Debian Python > library package? > > Debian Policy =C2=A712.3 says: > > [=E2=80=A6] installing the documentation into the documentation direc= tory of > the main package is preferred since it is independent of the > packaging method and will be easier for users to find. > > 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 insta= ll the > documentation to =E2=80=98/usr/share/doc/libfoo/=E2=80=99. > > > 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. > > The documentation package =E2=80=98python-foo-doc=E2=80=99 then has no on= e obvious place > to install the documentation: > > * Installing to =E2=80=98/usr/share/doc/python-foo-doc/=E2=80=99 is disco= uraged by the > 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 documentation. > > * Installing to =E2=80=98/usr/share/doc/python-foo/=E2=80=99 or > =E2=80=98/usr/share/doc/python3-foo/=E2=80=99 is incorrect if the corre= sponding > library package is not installed. > > Compounding this is the fact we are (rightly, IMO) moving toward Python > 3 as the primary runtime, and discouraging new Python 2 packages. Is > =E2=80=98python3-foo=E2=80=99 then the =E2=80=9Cmain package=E2=80=9D by = the Policy statement above? > > 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 the pro= blem of *which* > package should be assumed. > > 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? > > > 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. > > There is varying practice among packages, and anyway just because some > package does it a particular way doesn't mean I should copy that without > knowing whether it's a good idea. > > What to do? > > -- > \ =E2=80=9CI put contact lenses in my dog's eyes. They had l= ittle | > `\ pictures of cats on them. Then I took one out and he ran around | > _o__) in circles.=E2=80=9D =E2=80=94= Steven Wright | > Ben Finney >