Consistent location for library documentation

[Ben Finney <bignose@debian.org>]

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