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