Re: Consistent location for library documentation
Thanks - so the policy is that the preference is that documentation is
installed in /usr/share/doc/<main package>, but that
/usr/share/doc/<main package>-doc is also allowed. The justification
is that the documentation is easier for users to find this way.
dh_installdocs attempts to compute the name of main package by
chopping the -doc off the end of the doc package name in
compute_doc_main_package [1].
So, my question is, have we as a team decided that:
a) We want to install documentation to /usr/share/doc/<main package>
not /usr/share/doc/<main package>-doc
b) the Python 2 package is the main package and the Python 3 package is not?
It seems to me that when Python2 is dropped, compute_doc_main_package
will no longer be able to compute the main package (because the
python-<package> packages will no longer exist) and existing
python-<package>-doc packages which install to
/usr/share/doc/<package> will be in breach of the policy.
[1] https://salsa.debian.org/debian/debhelper/blob/master/lib/Debian/Debhelper/Dh_Lib.pm
Christopher
On 3 March 2018 at 09:56, Scott Kitterman <debian@kitterman.com> wrote:
> 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
>
Reply to: