generating extra documentation (port:kdelibs4)

[Ryan Schmidt]

On May 7, 2015, at 12:18 PM, René J.V. Bertin wrote:

> I thought it'd be nice to have the kdelibs4 documentation in Qt help (.qch) format. It is available online, but seriously outdated and will of course not reflect any OS X specific changes that we made.
> 
> There is a script in the doc/api directory that generates this documentation file, but it hogs the computer for over an hour. My initial thought had been to generate it unconditionally if the user selects the +docs variant, but not when there is so much overhead. What alternatives are there? I could create a subport, but that would still cause this documentation to be rebuilt each time an update is pushed and the user does an `upgrade outdated`, which seems overkill to me. If it were just me I'd let the generation depend on the presence of a specific env. variable, in the +docs variant; would that be acceptable?

No, it would not be acceptable for a port to build differently based on an environment variable, because port builds should be repeatable and predictable and should not depend on aspects of the users environment. To that end, MacPorts clears the environment variables; by the time a port is processed, it is no longer possible to access the user's environment.

Documentation -- especially documentation that takes a long time to build, has a lot of extra dependencies, or takes a lot of disk space -- should be in a separate port (possibly subport), not in a variant.