From ae1d99eafb2268eb44eb2d74d7098bf88159b8c9 Mon Sep 17 00:00:00 2001 From: Eike Ziller Date: Fri, 10 Mar 2017 14:46:22 +0100 Subject: Refactor documentation generation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 Reviewed-by: Topi Reiniö Reviewed-by: Joerg Bornemann --- doc/config/qbs-project.qdocconf | 7 ++- doc/doc.pri | 23 +++----- doc/doc_shared.pri | 14 +++++ doc/doc_targets.pri | 114 +++++++++++++++++++++++++--------------- 4 files changed, 96 insertions(+), 62 deletions(-) create mode 100644 doc/doc_shared.pri 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/$$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 -- cgit v1.2.3