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

Groups > linux.debian.maint.python > #9628 > unrolled thread

Consistent location for library documentation

Back to article view | Back to linux.debian.maint.python

Contents

  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

#9628 — Consistent location for library documentation

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

[toc] | [next] | [standalone]

#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-<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
>

[toc] | [prev] | [next] | [standalone]

#10222

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

[toc] | [prev] | [next] | [standalone]

#10223

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
>

[toc] | [prev] | [standalone]

Back to top | Article view | linux.debian.maint.python

csiph-web