Refactor documentation generation

Update doc_targets.pri to changes made in Qt Creator and create
a pri file for Qbs documentation for inclusion in Qt Creator.

Change-Id: I8c3258c193d3e526e6a345c0efee18dcdd11cfc8
Reviewed-by: Leena Miettinen <riitta-leena.miettinen@qt.io>
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
Reviewed-by: Joerg Bornemann <joerg.bornemann@qt.io>

4 files changed, 96 insertions, 62 deletions

diff --git a/doc/config/qbs-project.qdocconf b/doc/config/qbs-project.qdocconf
index 068085803..197a01260 100644
--- a/doc/config/qbs-project.qdocconf
+++ b/doc/config/qbs-project.qdocconf
@@ -7,10 +7,9 @@ project     = "Qbs"
 description = "Qbs Manual"
 
 headerdirs =
-sourcedirs = $SRCDIR
-imagedirs = $SRCDIR/images $SRCDIR/templates/images
-outputdir = $OUTDIR
-exampledirs = $SRCDIR
+sourcedirs = ..
+imagedirs = ../images ../templates/images
+exampledirs = ..
 
 include(macros.qdocconf)
 sources.fileextensions  = "*.qdoc"
diff --git a/doc/doc.pri b/doc/doc.pri
index 052790f2f..84583a870 100644
--- a/doc/doc.pri
+++ b/doc/doc.pri
@@ -1,24 +1,13 @@
 include(../src/install_prefix.pri)
 
-QDOC_BIN = $$shell_path($$[QT_INSTALL_BINS]/qdoc)
-QDOC_MAINFILE = $$PWD/qbs.qdocconf
-HELPGENERATOR = $$shell_path($$[QT_INSTALL_BINS]/qhelpgenerator)
+include(doc_shared.pri)
 
-include(doc_targets.pri)
+DOC_OUTDIR_POSTFIX = /html
+DOC_HTML_INSTALLDIR = $$QBS_INSTALL_PREFIX/share/doc/qbs
+DOC_QCH_OUTDIR = $$OUT_PWD/doc
+DOC_QCH_INSTALLDIR = $$QBS_INSTALL_PREFIX/share/doc/qbs
 
-html_docs.depends = qbs_html_docs
-html_docs_online.depends = qbs_html_docs_online
-qch_docs.depends = qbs_qch_docs
-docs_online.depends = qbs_docs_online
-install_docs.depends = qbs_install_docs
-docs.depends = qbs_docs
-QMAKE_EXTRA_TARGETS += \
-    docs \
-    docs_online \
-    html_docs \
-    html_docs_online \
-    install_docs \
-    qch_docs
+include(doc_targets.pri)
 
 fixnavi.commands = \
     cd $$shell_path($$PWD) && \
diff --git a/doc/doc_shared.pri b/doc/doc_shared.pri
new file mode 100644
index 000000000..3e4eccf48
--- /dev/null
+++ b/doc/doc_shared.pri
@@ -0,0 +1,14 @@
+include(../qbs_version.pri)
+
+qbsdoc_version.name = QBS_VERSION
+qbsdoc_version.value = $$QBS_VERSION
+qbsdoc_versiontag.name = QBS_VERSION_TAG
+qbsdoc_versiontag.value = $$replace(QBS_VERSION, "[-.]", )
+qbsdoc_qtdocs.name = QT_INSTALL_DOCS
+qbsdoc_qtdocs.value = $$[QT_INSTALL_DOCS/src]
+QDOC_ENV += qbsdoc_version qbsdoc_versiontag qbsdoc_qtdocs
+
+build_online_docs: \
+    DOC_FILES += $$PWD/qbs-online.qdocconf
+else: \
+    DOC_FILES += $$PWD/qbs.qdocconf
diff --git a/doc/doc_targets.pri b/doc/doc_targets.pri
index 79f485721..16fbfa2b4 100644
--- a/doc/doc_targets.pri
+++ b/doc/doc_targets.pri
@@ -1,49 +1,81 @@
-# This pri file can be included by other projects that want to provide the qbs documentation.
-# Common variables like QDOC_BIN or HELPGENERATOR must be provided by the including file.
-QBS_VERSION_TAG = $$replace(QBS_VERSION, "[-.]", )
-
-isEmpty(QBS_DOCS_BUILD_DIR): QBS_DOCS_BUILD_DIR = $$OUT_PWD/doc
-isEmpty(QBS_HTML_DOC_PATH): QBS_HTML_DOC_PATH = $$QBS_DOCS_BUILD_DIR/html
-equals(QMAKE_DIR_SEP, /) {   # unix, mingw+msys
-    QDOC = SRCDIR=$$PWD OUTDIR=$$QBS_HTML_DOC_PATH QBS_VERSION=$$QBS_VERSION QBS_VERSION_TAG=$$QBS_VERSION_TAG QT_INSTALL_DOCS=$$[QT_INSTALL_DOCS] $$QDOC_BIN
-} else: mingw {
-    # The lack of spaces in front of the && is necessary!
-    QDOC = set SRCDIR=$$PWD&& set OUTDIR=$$QBS_HTML_DOC_PATH&& set QBS_VERSION=$$QBS_VERSION&& set QBS_VERSION_TAG=$$QBS_VERSION_TAG&& set QT_INSTALL_DOCS=$$[QT_INSTALL_DOCS]&& $$QDOC_BIN
-} else {   # nmake
-    QDOC = set SRCDIR=$$PWD $$escape_expand(\\n\\t) \
-           set OUTDIR=$$QBS_HTML_DOC_PATH $$escape_expand(\\n\\t) \
-           set QBS_VERSION=$$QBS_VERSION $$escape_expand(\\n\\t) \
-           set QBS_VERSION_TAG=$$QBS_VERSION_TAG $$escape_expand(\\n\\t) \
-           set QT_INSTALL_DOCS=$$[QT_INSTALL_DOCS] $$escape_expand(\\n\\t) \
-           $$QDOC_BIN
-}
+# Creates targets for building documentation
+# (adapted from qt_docs.prf)
+#
+# Usage: Define variables (details below) and include this pri file afterwards.
+#
+# QDOC_ENV            - environment variables to set for the qdoc call (see example below)
+# DOC_INDEX_PATHS     - list of paths where qdoc should search for index files of dependent
+#                       modules (Qt index path is included by default)
+# DOC_FILES           - list of qdocconf files
+# DOC_OUTDIR_POSTFIX  - html is generated in $$OUT_PWD/<qdocconf_name>$$DOC_OUTDIR_POSTFIX
+# DOC_HTML_INSTALLDIR - path were to install the directory of html files
+# DOC_QCH_OUTDIR      - path where to generated the qch files
+# DOC_QCH_INSTALLDIR  - path where to install the qch files
+#
+# Example for QDOC_ENV:
+# ver.name = VERSION
+# ver.value = 1.0.2
+# foo.name = FOO
+# foo.value = foo
+# QDOC_ENV = ver foo
+
+isEmpty(DOC_FILES): error("Set DOC_FILES before including doc_targets.pri")
+isEmpty(DOC_HTML_INSTALLDIR): error("Set DOC_HTML_INSTALLDIR before including doc_targets.pri")
+isEmpty(DOC_QCH_OUTDIR): error("Set DOC_QCH_OUTDIR before including doc_targets.pri")
+isEmpty(DOC_QCH_INSTALLDIR): error("Set DOC_QCH_INSTALLDIR before including doc_targets.pri")
+
+QT_TOOL_ENV = $$QDOC_ENV
+qtPrepareTool(QDOC, qdoc)
+QT_TOOL_ENV =
+
+!build_online_docs: qtPrepareTool(QHELPGENERATOR, qhelpgenerator)
+
+DOCS_BASE_OUTDIR = $$OUT_PWD/doc
+DOC_INDEXES += -indexdir $$shell_quote($$[QT_INSTALL_DOCS])
+for (index_path, DOC_INDEX_PATHS): \
+    DOC_INDEXES += -indexdir $$shell_quote($$index_path)
 
-QBS_QHP_FILE = $$QBS_HTML_DOC_PATH/qbs.qhp
-QBS_QCH_FILE = $$QBS_DOCS_BUILD_DIR/qbs.qch
+for (doc_file, DOC_FILES) {
+    !exists($$doc_file): error("Cannot find documentation specification file $$doc_file")
+    DOC_TARGET = $$replace(doc_file, ^(.*/)?(.*)\\.qdocconf$, \\2)
+    DOC_TARGETDIR = $$DOC_TARGET
+    DOC_OUTPUTDIR = $${DOCS_BASE_OUTDIR}/$${DOC_TARGETDIR}$${DOC_OUTDIR_POSTFIX}
 
-QBS_HELP_DEP_FILES = \
-    $$PWD/qbs.qdoc \
-    $$PWD/qbs.qdocconf
+    html_docs_$${DOC_TARGET}.commands = $$QDOC -outputdir $$shell_quote($$DOC_OUTPUTDIR) $$doc_file $$DOC_INDEXES
+    QMAKE_EXTRA_TARGETS += html_docs_$${DOC_TARGET}
 
-qbs_html_docs.commands = $$QDOC $$PWD/qbs.qdocconf
-qbs_html_docs.depends += $$QBS_HELP_DEP_FILES
+    !isEmpty(html_docs.commands): html_docs.commands += &&
+    html_docs.commands += $$eval(html_docs_$${DOC_TARGET}.commands)
 
-qbs_qch_docs.commands = $$HELPGENERATOR -o $$shell_quote($$QBS_QCH_FILE) $$QBS_QHP_FILE
-qbs_qch_docs.depends += qbs_html_docs
+    inst_html_docs.files += $$DOC_OUTPUTDIR
 
-isEmpty(QBS_DOCS_INSTALL_DIR): QBS_DOCS_INSTALL_DIR = $${QBS_INSTALL_PREFIX}/share/doc/qbs
-inst_qbs_qch_docs.files = $$QBS_QCH_FILE
-inst_qbs_qch_docs.path = $$QBS_DOCS_INSTALL_DIR
-inst_qbs_qch_docs.CONFIG += no_check_exist no_default_install
-INSTALLS += inst_qbs_qch_docs
+    !build_online_docs {
+        qch_docs_$${DOC_TARGET}.commands = $$QHELPGENERATOR $$shell_quote($$DOC_OUTPUTDIR/$${DOC_TARGET}.qhp) -o $$shell_quote($$DOC_QCH_OUTDIR/$${DOC_TARGET}.qch)
+        qch_docs_$${DOC_TARGET}.depends = html_docs_$${DOC_TARGET}
+        QMAKE_EXTRA_TARGETS += qch_docs_$${DOC_TARGET}
 
-inst_qbs_html_docs.files = $$QBS_HTML_DOC_PATH
-inst_qbs_html_docs.path = $$inst_qbs_qch_docs.path
-inst_qbs_html_docs.CONFIG += no_check_exist no_default_install directory
-INSTALLS += inst_qbs_html_docs
+        !isEmpty(qch_docs.commands): qch_docs.commands += &&
+        qch_docs.commands += $$eval(qch_docs_$${DOC_TARGET}.commands)
+
+        inst_qch_docs.files += $$DOC_QCH_OUTDIR/$${DOC_TARGET}.qch
+    }
+}
+
+!build_online_docs {
+    qch_docs.depends = html_docs
+    inst_qch_docs.path = $$DOC_QCH_INSTALLDIR
+    inst_qch_docs.CONFIG += no_check_exist no_default_install no_build
+    install_docs.depends = install_inst_qch_docs
+    docs.depends = qch_docs
+    INSTALLS += inst_qch_docs
+    QMAKE_EXTRA_TARGETS += qch_docs install_docs
+} else {
+    docs.depends = html_docs
+}
 
-qbs_install_docs.depends = install_inst_qbs_qch_docs install_inst_qbs_html_docs
-QMAKE_EXTRA_TARGETS += qbs_install_docs
+inst_html_docs.path = $$DOC_HTML_INSTALLDIR
+inst_html_docs.CONFIG += no_check_exist no_default_install directory
+INSTALLS += inst_html_docs
+install_docs.depends += install_inst_html_docs
 
-qbs_docs.depends = qbs_qch_docs
-QMAKE_EXTRA_TARGETS += qbs_html_docs qbs_qch_docs qbs_docs
+QMAKE_EXTRA_TARGETS += html_docs docs