Re: On accepting pre-generated doc from upstream

[Goswin von Brederlow <goswin-v-b@web.de>]

On Thu, Jun 06, 2013 at 11:35:46PM -0300, Lisandro Damián Nicanor Pérez Meyer wrote:
> Hi everyone. First of all, I'm cross-posting this between legal and devel 
> because I really don't know to which of them belongs (or maybe it does in 
> both).
> 
> The issue is this: Qt 5 has grown so large (850+MB unpacked in the single-
> source tarball, will continue growing) that upstream also provides it as 
> submodules. 15 of them in 5.0.2.
> 
> Of course, in terms of maintainance, we have opted for the submodules choice.
> 
> Building the full doc could be done in two ways:
> 
> - Using the full source tarball. Saddly this means having to compile most of 
> it in order to get the tools for building the doc, or hacking far too much the 
> build system to do something else.
> 
> - Build each submodule's doc.
> 
> While the second option seems the clear winner, there is a gotcha: you need 
> packages 1 and 2 built and in the archive to build the documentation. 
> Including their documentation. Packages 3 to 15 should not present further 
> problems.
> 
> So this can be solved by packaging 1 and 2 without docs and pushing them to 
> the archive. Then, once 1 and 2 have been built on *every* arch, repackage 1 
> and 2 with the documentation and upload them.
> 
> This means that we need to bootstrap the packages. And we may need to do it 
> for every major release (5.1, 5.2,...), although it's not confirmed.
> 
> As a possible workaround, upstream has suggested to provide the documentation 
> already generated (could be for the submodules and/or the full doc, this has 
> not been discussed yet). My first reaction has been to think that this will 
> not be allowed in Debian, but giving it some more thought,:
> 
> - We do have the source code for generating it (preferred form of 
> modification).
> 
> - We can build it, but it requires lot of work... and avoid FTBFSs while 
> bootstrapping ;)
> 
> So, could we accept pre-generated documentation in this case?
> 
> Kinds regards, and thanks in advance for your time, Lisandro.

- Option 3:

(Note: I'm assuming you are generating API docs directly fromt the
source files. So the input for the doc building is not seperable from
the actual source.)

For packages 1 and 2 build without docs but also build a
package{1,2}-src package.

Have another source package{1,2}-doc that Build-Depends:
tools-for-doc-building, package{1,2}-src and sets Build-Using:
package{1,2}-src. This would then generate the API docs from the
source files using the tools and sources from the package{1,2} builds.
On update you would usualy only need to bump the version for this
package.

MfG
	Goswin