qdoc: qdoc now can run in 2 passes

Two command line options have been added, -prepare and -generate.
If you run qdoc with -prepare, qdoc reads and parses the source
files but does not generate the documentation. It only creates
the .index file for the module you are running qdoc on.

If you run qdoc with -generate, qdoc reads and parses the source
files as well as the .index files created by running qdoc with
-prepare, and it generates the documentation but no .index file.

If you run without either option, qdoc runs as before, i.e. it
runs both passes as a single pass.

Task number: QTBUG-27539

Change-Id: Idbfe3f0f9dff58283596b504f00dff3f70f6e371
Reviewed-by: Tor Arne Vestbø <tor.arne.vestbo@digia.com>
Reviewed-by: Martin Smith <martin.smith@digia.com>

diff --git a/src/tools/qdoc/ditaxmlgenerator.cpp b/src/tools/qdoc/ditaxmlgenerator.cpp
index f7700ce..563df61 100644 (file)
--- a/src/tools/qdoc/ditaxmlgenerator.cpp
+++ b/src/tools/qdoc/ditaxmlgenerator.cpp
@@ -673,19 +673,26 @@ GuidMap* DitaXmlGenerator::lookupGuidMap(const QString& fileName)
 void DitaXmlGenerator::generateTree()
 {
     qdb_->buildCollections();
-    Generator::generateTree();
-    generateCollisionPages();
-
-    QString fileBase = project.toLower().simplified().replace(QLatin1Char(' '), QLatin1Char('-'));
-    qdb_->generateIndex(outputDir() + QLatin1Char('/') + fileBase + ".index",
-                        projectUrl,
-                        projectDescription,
-                        this);
-    writeDitaMap();
-    /*
-      Generate the XML tag file, if it was requested.
-     */
-    qdb_->generateTagFile(tagFile_, this);
+    if (!runPrepareOnly()) {
+        Generator::generateTree();
+        generateCollisionPages();
+    }
+
+    if (!runGenerateOnly()) {
+        QString fileBase = project.toLower().simplified().replace(QLatin1Char(' '), QLatin1Char('-'));
+        qdb_->generateIndex(outputDir() + QLatin1Char('/') + fileBase + ".index",
+                            projectUrl,
+                            projectDescription,
+                            this);
+    }
+
+    if (!runPrepareOnly()) {
+        writeDitaMap();
+        /*
+          Generate the XML tag file, if it was requested.
+        */
+        qdb_->generateTagFile(tagFile_, this);
+    }
 }
 
 static int countTableColumns(const Atom* t)

diff --git a/src/tools/qdoc/generator.cpp b/src/tools/qdoc/generator.cpp
index 1c7727d..c6db340 100644 (file)
--- a/src/tools/qdoc/generator.cpp
+++ b/src/tools/qdoc/generator.cpp
@@ -96,6 +96,7 @@ QStringList Generator::styleDirs;
 QStringList Generator::styleFiles;
 bool Generator::debugging_ = false;
 bool Generator::noLinkErrors_ = false;
+Generator::Passes Generator::qdocPass_ = Both;
 
 void Generator::setDebugSegfaultFlag(bool b)
 {

diff --git a/src/tools/qdoc/generator.h b/src/tools/qdoc/generator.h
index 30f2219..3dc3b84 100644 (file)
--- a/src/tools/qdoc/generator.h
+++ b/src/tools/qdoc/generator.h
@@ -68,6 +68,8 @@ class QDocDatabase;
 class Generator
 {
 public:
+    enum Passes { Both, Prepare, Generate };
+
     Generator();
     virtual ~Generator();
 
@@ -90,6 +92,9 @@ public:
     static void setDebugSegfaultFlag(bool b);
     static bool debugging() { return debugging_; }
     static bool noLinkErrors() { return noLinkErrors_; }
+    static void setQDocPass(Passes pass) { qdocPass_ = pass; }
+    static bool runPrepareOnly() { return (qdocPass_ == Prepare); }
+    static bool runGenerateOnly() { return (qdocPass_ == Generate); }
 
 protected:
     virtual void beginSubPage(const InnerNode* node, const QString& fileName);
@@ -193,6 +198,7 @@ private:
     static QStringList styleFiles;
     static bool debugging_;
     static bool noLinkErrors_;
+    static Passes qdocPass_;
 
     void appendFullName(Text& text,
                         const Node *apparentNode,

diff --git a/src/tools/qdoc/htmlgenerator.cpp b/src/tools/qdoc/htmlgenerator.cpp
index a772165..17dc40f 100644 (file)
--- a/src/tools/qdoc/htmlgenerator.cpp
+++ b/src/tools/qdoc/htmlgenerator.cpp
@@ -243,21 +243,27 @@ QString HtmlGenerator::format()
 void HtmlGenerator::generateTree()
 {
     qdb_->buildCollections();
-    Generator::generateTree();
-    generateCollisionPages();
+    if (!runPrepareOnly()) {
+        Generator::generateTree();
+        generateCollisionPages();
+    }
 
-    QString fileBase = project.toLower().simplified().replace(QLatin1Char(' '), QLatin1Char('-'));
-    qdb_->generateIndex(outputDir() + QLatin1Char('/') + fileBase + ".index",
-                        projectUrl,
-                        projectDescription,
-                        this);
+    if (!runGenerateOnly()) {
+        QString fileBase = project.toLower().simplified().replace(QLatin1Char(' '), QLatin1Char('-'));
+        qdb_->generateIndex(outputDir() + QLatin1Char('/') + fileBase + ".index",
+                            projectUrl,
+                            projectDescription,
+                            this);
+    }
 
-    helpProjectWriter->generate();
-    generateManifestFiles();
-    /*
-      Generate the XML tag file, if it was requested.
-     */
-    qdb_->generateTagFile(tagFile_, this);
+    if (!runPrepareOnly()) {
+        helpProjectWriter->generate();
+        generateManifestFiles();
+        /*
+          Generate the XML tag file, if it was requested.
+        */
+        qdb_->generateTagFile(tagFile_, this);
+    }
 }
 
 /*!

diff --git a/src/tools/qdoc/main.cpp b/src/tools/qdoc/main.cpp
index 03974c5..5fbc01f 100644 (file)
--- a/src/tools/qdoc/main.cpp
+++ b/src/tools/qdoc/main.cpp
@@ -131,6 +131,10 @@ static void printHelp()
                              "Specify output directory, overrides setting in qdocconf file\n"
                              "    -outputformat  "
                              "Specify output format, overrides setting in qdocconf file\n"
+                             "    -prepare        "
+                             "Run qdoc only to generate an index file, not the docs\n"
+                             "    -generate        "
+                             "Run qdoc to read the index files and generate the docs\n"
                              "    -showinternal  "
                              "Include content marked internal\n"
                              "    -version       "
@@ -594,6 +598,12 @@ int main(int argc, char **argv)
         else if (opt == "-debug") {
             Generator::setDebugSegfaultFlag(true);
         }
+        else if (opt == "-prepare") {
+            Generator::setQDocPass(Generator::Prepare);
+        }
+        else if (opt == "-generate") {
+            Generator::setQDocPass(Generator::Generate);
+        }
         else {
             qdocFiles.append(opt);
         }