FTBFS due to missing documentation file

[Peter Mattern]

Building recent VCS checkouts fails, apparently due to some missing documentation file

$ cd src/
$ qmake-qt5 speedcrunch.pro 
WARNING: Failure to find: doc/manual.qrc
/usr/lib/qt/bin/rcc: File does not exist 'doc/manual.qrc'

Bisecting suggests it's regression introduced in b305844.

[Helder Correia]

Hi, Peter. On my end, the Makefile is still created, and the build works. Can you check on your side? Maybe @fk can help better than me.

[Felix Krull]

That's just a warning. You should indeed still get a Makefile and building should work. Unfortunately, I don't think there's a way not to have that warning with the current qmake files.

[Peter Mattern]

Turns out it was a stupid dependency issue.
But I dare say that I was sort of tricked into it to some degree: Getting

$ qmake-qt5 speedcrunch.pro 
Project MESSAGE: PYTHON_EXECUTABLE = python
Project MESSAGE: QCOLLECTIONGENERATOR_EXECUTABLE = /usr/lib/qt/bin/qcollectiongenerator
Project MESSAGE: SPHINX_BUILD_EXECUTABLE = sphinx-build
WARNING: Failure to find: doc/manual.qrc
/usr/lib/qt/bin/rcc: File does not exist 'doc/manual.qrc'

and seeing make fail made me assume the failure was due to lack of file manual.qrc while in fact the absence of that file indeed doesn't matter and the build failed as sphinx-build wasn't available.
Tests revealed that all three messages Project MESSAGE: [...] depicted above stay the very same when the corresponding binary is in fact missing.
Shouldn't this eventually be changed?

On a side note speedcrunch seems to depend on quark-sphinx-theme which at first glance isn't available e. g. in the official repositories of Arch Linux or Debian so people will have to fiddle with pip on the command line in order to get speedcrunch running. This can probably be expected from users who want to use VCS code but I wonder whether the use of that theme makes sense with regards to an eventual release.

[Helder Correia]

Also not very fond of the pipthing. @fk Any way of getting it to work by including a copy of the theme locally?

[Pol Welter]

A local copy is no problem. Felix and I thought pip was easy enough to use to not represent a barrier. The user already needs to install sphinx and possibly some more dependencies, like sphinx-intl, and pip is arguably the easiest way to do so.

@pmattern FYI quark-sphinx-theme has been created specifically for SpeedCrunch, and for good reason, so its inclusion in the release is out of question :)

Personally I think anyone planning to build a Qt app from source should be familiar with a terminal :P

Jokes aside, I am still a bit skeptical about the need to build the documentation each time we compile the main application. Sure enough, this is super practical right now, since we are in the process of writing. In the future, writing the documentation and doing development work are probably no more linked this tightly. I think we could separate those tasks, running doc-tool manually each time we want to update the docs. Building the application would then grab the .qrc it finds in doc-tool's build directory. This qrc could be added to git (even though it is a binary format), so that a user that clones the repo does not need any of sphinx and friends. Also these weird issues with non-existing qrc's go away. CMake and qmake files would become simpler too.

Essentially the same workflow we currently have with the .ts files.

Personally I don't mind the current process (it surely is nicely automated, except for the translations). But I am open to changes as well.

[Helder Correia]

Essentially the same workflow we currently have with the .ts files. - Precisely what I was going to say, and for good reason. I'm fine with your proposal, I think that's what makes sense (detaching the docs building).