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 <bign...@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
