Install documentation for a library to the library's documentation directory

[Ben Finney <bignose@debian.org>]

Howdy all,

How should I make library documentation available at a single obvious
location, for any of several binary packages of the library?


I am working on a package with the following dependencies::

    Source: pyfoo

    Package: python3-foo
    Section: python
    Suggests: python-foo-doc

    Package: python-foo
    Section: python
    Suggests: python-foo-doc

    Package: python-foo-doc
    Section: doc

The ‘python-foo-doc’ package installs the HTML documentation for the
library. What I want is to install that into a single location, that all
three packages will use.


Maybe ‘/usr/share/doc/python-foo/’? The ‘dh_installdoc(1)’ tool has an
option to enable that. The man page says::

    --link-doc=package
        Make the documentation directory of all packages acted on be a
        symlink to the documentation directory of package. This has no
        effect when acting on package itself, or if the documentation
        directory to be created already exists when dh_installdocs is
        run. To comply with policy, package must be a binary package
        that comes from the same source package.

That sounds very much like what I want. So, in ‘debian/rules’::

    override_dh_installdocs:
    	dh_installdocs --link-doc=python-foo

That has the following effects:

* All three packages use ‘/usr/share/doc/python-foo/’ for their
  documentation target.

* Package ‘python3-foo’ installs a symlink in ‘/usr/share/doc/’ named
  ‘python3-foo’, pointing to ‘python-foo’.
  Package ‘python-foo-doc’ installs a symlink in ‘/usr/share/doc/’ named
  ‘python-foo-doc’, pointing to ‘python-foo’.

* Package ‘python3-foo’ gains “Depends: python-foo (= 1.2.3-1)”.
  Package ‘python-foo-doc’ gains “Depends: python-foo (= 1.2.3-1)”.

That last point is definitely not what I want; the documentation package
should not depend on the library package, and the Python 3 library
should not depend on the Python 2 library.

I understand why this dependency is enforced: it makes the directory
available to be the target of the symlink. But the dependency brings in
the whole library, which is not what I want.


How can I install the documentation at ‘/usr/share/doc/python-foo/’,
without spurious dependencies like above, and using the tools normally?

-- 
 \          “Computer perspective on Moore's Law: Human effort becomes |
  `\           twice as expensive roughly every two years.” —anonymous |
_o__)                                                                  |
Ben Finney