cmake @3.2.2_0+docs+gui: build documentation in Qt help/Assistant format

[RJVB (René Bertin)]

cmake uses sphinx to generate its documentation, which means a .qch version can be made for use with Qt's Assistant. I propose to do this automatically when combining +docs with +gui and +python34 . The latter condition is because Python 2.7 appears to crash when building the documentation; I have not checked if this also occurs without building the documentation in Qt format. (That does not seem impossible because the .qch file is generated from the HTML documentation, and appears to be built in the destroot step while the crash occurs during the build phase.)

I've also removed my -bundle patch, which turned out not to be a good idea (as I already signalled a while ago).

[larryv (Lawrence Velázquez)]

This is confusing and non-obvious. There’s no suggestion that this…

sudo port install cmake +gui +docs +python34

… should produce more documentation than this…

sudo port install cmake +gui +docs +python27

… yet that is exactly what will happen.

A more obvious approach would be to add a variant for the Qt help that required +gui +docs +python34. Another possibility would be to ditch the Python variants and have +docs use Python 3.4 Sphinx and build the Qt help unconditionally.

[RJVB (René Bertin)]

Replying to larryv@…:

… should produce more documentation than this…

No, I didn't add anything to the +docs description, but there is not "more" documentation that is built. The same documentation is simply compiled in an additional format, which isn't the same thing. It could use that description, but lacking that I don't see why anyone would be confused. Except by the fact that getting the Qt help requires a specific python variant, but that could also go in the variant description.

A more obvious approach would be to add a variant for the Qt help that required +gui +docs +python34. Another possibility would be to ditch the Python variants and have +docs use Python 3.4 Sphinx and build the Qt help unconditionally.

I personally find that the port already has enough variants and variants of variants, and I think Michael's intention with that is to allow choice instead of enforcing choice on users (Qt4 or Qt5, python2.7 or python3.4). The only possible interest of a specific Qt help variant that I can see is to install that help format *instead* of the HTML version.

Compiling the help in Qt format requires Qt, which is why I made it a side-effect of +gui+docs.

Anyway, my expectation here was mostly to remind Michael of the possibility to provide the help in Qt format, he's capable enough to see how to implement it exactly.

[michaelld (Michael Dickens)]

I just pushed r138729, which fixes an issue where the PYTHON_EXECUTABLE might not match the specified version of Sphinx; it's generally wiser if they match, though they don't actually have to. After this change, no matter what I try I cannot coerce the Qt help documentation to build; Python 2.7 and 3.4 both fail eventually. So, I just removed this addition & will leave it out until testing shows that it does work.

I'm closing this ticket as "wontfix" because of these issues. If anybody can come up with patches to get this feature working, independently using either Python 2.7 or 3.4, then please reopen this ticket & attach your patches for us to test / verify.