Re: Consistent location for library documentation
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
>
Reply to: