Add config option to build documentation as a two-step process

The new 'prepare_docs' CONFIG option triggers the documentation rules in
default_post to generate two extra targets: prepare_docs and generate_docs.
The prepare_docs stage runs qdoc with the -prepare option, which means qdoc
will only generate index files, and the generate_docs stage will call
qdoc with -generate, which reads the index files and generates the final
output. The regular docs target will then run the prepare_docs target
for all submodules before running the generate_docs target.

This ensures that when generating the final output, qdoc has all the
index files for all the other modules available, to be able to resolve
cross-references between the various Qt modules.

This patch needs a follow-up in qt5.git to add CONFIG+=prepare_docs, so
that the root Qt5 build will be able to hook into this new behavior.

Change-Id: I654d7f0d4d5a41d9be208e6d3a8923bf0194f9ad
Reviewed-by: Jerome Pasion <jerome.pasion@digia.com>

1 files changed, 17 insertions, 2 deletions

diff --git a/mkspecs/features/default_post.prf b/mkspecs/features/default_post.prf
index a77738222f..86ce168a8e 100644
--- a/mkspecs/features/default_post.prf
+++ b/mkspecs/features/default_post.prf
@@ -59,7 +59,13 @@ QMAKE_LIBDIR += $$QMAKE_LIBDIR_POST
 
 !contains(QMAKE_EXTRA_TARGETS, docs) {
     contains(TEMPLATE, subdirs) {
-        prepareRecursiveTarget(docs)
+        prepare_docs {
+            prepareRecursiveTarget(prepare_docs)
+            prepareRecursiveTarget(generate_docs)
+            docs.commands = $(MAKE) -f $(MAKEFILE) prepare_docs && $(MAKE) -f $(MAKEFILE) generate_docs
+        } else {
+            prepareRecursiveTarget(docs)
+        }
     } else {
         # apps and libs only generate docs if QMAKE_DOCS is set
         !isEmpty(QMAKE_DOCS) {
@@ -68,10 +74,19 @@ QMAKE_LIBDIR += $$QMAKE_LIBDIR_POST
             for(index, QMAKE_DOCS_INDEX):QDOC_INDEX += -indexdir $$index
             !isEmpty(QMAKE_DOCS_OUTPUTDIR):QMAKE_DOCS_OPTIONS += -outputdir $$QMAKE_DOCS_OUTPUTDIR
             !isEmpty(QMAKE_DOCS_INSTALLDIR):QMAKE_DOCS_OPTIONS += -installdir $$QMAKE_DOCS_INSTALLDIR
-            docs.commands += $$QDOC $$QMAKE_DOCS_OPTIONS $$QDOC_INDEX $$QMAKE_DOCS
+            doc_command = $$QDOC $$QMAKE_DOCS_OPTIONS $$QDOC_INDEX $$QMAKE_DOCS
+
+            prepare_docs {
+                prepare_docs.commands += $$doc_command -prepare -no-link-errors
+                generate_docs.commands += $$doc_command -generate
+                docs.depends += generate_docs
+            } else {
+                docs.commands += $$doc_command
+            }
         }
     }
     QMAKE_EXTRA_TARGETS += docs
+    prepare_docs: QMAKE_EXTRA_TARGETS += prepare_docs generate_docs
 }
 
 !contains(QMAKE_EXTRA_TARGETS, install_docs) {