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

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

Re: Consistent location for library documentation

Show key headers only | View raw

Look at Debian Policy, section 12.3 Additional Documentation.  The answer is 
there.

Scott K

On Saturday, March 03, 2018 09:25:20 AM Christopher Hoskin wrote:
> 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-<package>-doc.docs (e.g. build/html) would get installed
> to /usr/share/doc/python-<package>-doc/ but with compat 11, they get
> installed to /usr/share/doc/python-<package>/.
> 
> >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 <bignose@debian.org> wrote:
> > Howdy all,
> > 
> > Where is the best location for library documentation of a Debian Python
> > library package?
> > 
> > Debian Policy §12.3 says:
> >     […] 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.
> > 
> > This is clear enough where a library package ‘libfoo’ is the main
> > package. The documentation package ‘libfoo-doc’ can install the
> > documentation to ‘/usr/share/doc/libfoo/’.
> > 
> > 
> > With the split in Python runtime systems, though, there is commonly not
> > a single “main package”. Typically there are two, ‘python3-foo’ and
> > ‘python-foo’.
> > 
> > The documentation package ‘python-foo-doc’ then has no one obvious place
> > to install the documentation:
> > 
> > * Installing to ‘/usr/share/doc/python-foo-doc/’ is discouraged by the
> > 
> >   above Policy section. I agree that is not necessarily an obvious place
> >   for a user to look for ‘python3-foo’ documentation.
> > 
> > * Installing to ‘/usr/share/doc/python-foo/’ or
> > 
> >   ‘/usr/share/doc/python3-foo/’ is incorrect if the corresponding
> >   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
> > ‘python3-foo’ then the “main package” by the Policy statement above?
> > 
> > A symlink could be used, from ‘/usr/share/doc/libfoo-doc’ to
> > ‘/usr/share/doc/libfoo’. But that still runs into the problem 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
> > “one obvious way” 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?
> > 
> > --
> > 
> >  \             “I put contact lenses in my dog's eyes. They had little |
> >  
> >   `\   pictures of cats on them. Then I took one out and he ran around |
> > 
> > _o__)                                      in circles.” —Steven Wright |
> > Ben Finney

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

Thread

Consistent location for library documentation Ben Finney <bignose@debian.org> - 2017-07-16 07:00 +0200
  Re: Consistent location for library documentation Christopher Hoskin <mans0954@debian.org> - 2018-03-03 10:30 +0100
    Re: Consistent location for library documentation Scott Kitterman <debian@kitterman.com> - 2018-03-03 11:00 +0100
      Re: Consistent location for library documentation Christopher Hoskin <christopher.hoskin@gmail.com> - 2018-03-03 13:00 +0100

csiph-web