Howdy all,
What is (the?) recommended way to have DebHelper build, from one source
package, a collection of binary packages including a documentation
binary package, all of which have the “main package” for their
documentation?
Debian Policy §12.3 says, of “Additional documentation”:
If the documentation is packaged separately, as package-doc for
example […] installing the documentation into the documentation
directory of the main package is encouraged since it is independent
of the packaging method and will be easier for users to find.
For a hypothetical source package ‘foo’ that builds binary packages:
* ‘foo’, that installs a program of that name
* ‘libfoo42’, that installs the run-time library
* ‘foo-doc’, that installs the user documentation
that passage of Policy §12.3 recommends one directory for the “main
package”, ‘/usr/share/doc/foo/’, and the user documentation from
‘foo-doc’ should be installed to there (maybe to
‘/usr/share/doc/foo/html/’).
The examples I'm dealing with often use Sphinx to build documentation
from source, if that matters; but I assume this should be relatively
standardised no matter what builds the documentation.
How do we then best convince DebHelper to make the “main package”
documentation directory when needed, construct ‘foo-doc’ so that it
installs that documentation to ‘/usr/share/doc/foo/…’, and symlink the
various binary package documentation directories to the main package
documentation directory?
In a recent discussion, this came up:
Stuart Prescott <[email protected]> writes:
> […] I'd also not do that dh_link dance until I was installing things
> from the staging output into the packages, but that's a matter of
> taste.
Stuart refers to this dance in the ‘towncrier’ packaging, in
‘debian/rules’:
=====
[…]
PACKAGE_NAME = towncrier
[…]
LIBRARY_PACKAGE_NAME = python3-${MAIN_PYTHON_PACKAGE}
DOC_PACKAGE_NAME = ${PACKAGE_NAME}-doc
[…]
override_dh_auto_build: ${private_bin_dir}
dh_link -p "${LIBRARY_PACKAGE_NAME}" \
usr/share/doc/"${LIBRARY_PACKAGE_NAME}" \
usr/share/doc/"${PACKAGE_NAME}"
dh_link -p "${DOC_PACKAGE_NAME}" \
usr/share/doc/"${DOC_PACKAGE_NAME}" \
usr/share/doc/"${PACKAGE_NAME}"
dh_auto_build
[…]
=====
and for completeness, here is the functional content of
‘debian/towncrier-doc.install’:
=====
docs/_build/html/ usr/share/doc/towncrier/
=====
This certainly is more complex than I want it to be. It's the latest
result of beating my forehead against DebHelper magic trying to convince
it to put things where I want them.
Am I missing something; can DebHelper do this automatically without
these manual ‘dh_link’ invocations?
--
\ “The Vatican is not a state.… a state must have people. There |
`\ are no Vaticanians.… No-one gets born in the Vatican except by |
_o__) an unfortunate accident.” —Geoffrey Robertson, 2010-09-18 |
Ben Finney
