From 21e8ef1fefa5f8f2e93da89510627373a8ccdd16 Mon Sep 17 00:00:00 2001
From: Jerome Pasion <jerome.pasion@digia.com>
Date: Tue, 4 Dec 2012 18:47:37 +0100
Subject: Doc: Added a README file for building documentation.

Change-Id: I5987af88f7e8efc1b3c4fb788e5fd985e53b08a1
Reviewed-by: Venugopal Shivashankar <venugopal.shivashankar@digia.com>
Reviewed-by: Leena Miettinen <riitta-leena.miettinen@digia.com>
---
 doc/README | 109 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 109 insertions(+)
 create mode 100644 doc/README

(limited to 'doc/README')

diff --git a/doc/README b/doc/README
new file mode 100644
index 0000000000..355f61d353
--- /dev/null
+++ b/doc/README
@@ -0,0 +1,109 @@
+Qt 5 Documentation
+==================
+
+New in Qt 5.0, each module has its own documentation package. The documentation
+resides in the module sources as well as the configuration files needed to build
+the module documentation. The main Qt 5.0 Reference Documentation resides in the
+qtdoc repository.
+
+There are two ways to build Qt documentation:
+* run "make docs" in qt5/ or in the repositories
+* run the QDoc tool for each module
+
+
+Running "make docs"
+===================
+
+To build the documentation using Makefiles, qtbase needs to be compiled and
+installed.
+
+Running qmake will create make targets to build the documentation:
+* html_docs - builds only the HTML documentation
+* qch_docs - packages the HTML documentation into QCH files for Qt Creator and
+             Qt Assistant.
+* docs - runs html_docs and qch_docs
+
+Note: qch_docs needs qhelpgenerator to package the documentation. qhelpgenerator
+is in the qttools repository.
+
+These make targets use qmake's QT_INSTALL_DOCS variable as the output directory.
+Running "qmake -query" will list the directory set to QT_INSTALL_DOCS.
+
+To create all of the modules' documentation, run "make docs" in the
+qt5 directory:
+    $> make docs            # builds the bundled modules' documentation
+
+It is also possible to build only a small subset of the documentation by using
+make:
+    $> cd qtbase
+    $> make docs            # builds the documentation for modules in qtbase
+
+    $> cd qtbase/src/sql
+    $> make docs            # builds only the Qt SQL documentation
+
+
+Running QDoc
+============
+
+QDoc is the tool for generating Qt documentation and is located in qtbase.
+The simplest way to compile QDoc is to compile qtbase or only the tools in
+qtbase.
+
+    $> cd qtbase/src
+    $> make sub-tools # compiles QDoc
+
+Each module has a QDoc configuration file (.qdocconf). To build a module's
+documentation, run the "qdoc" binary and pass the qdocconf file as a parameter.
+A mandatory "outputdir" must be specified.
+
+    $> qdoc doc/config/qtdoc.qdocconf -outputdir html
+
+    Note that QDoc will delete the contents of the "html" output directory.
+
+Packaging the Documentation
+===========================
+
+To package the documentation, the HTML files must be compiled
+into a QCH file (.qch).
+
+Required binaries:
+    * assistant - found in qttools
+    * qhelpgenerator - found in qttools
+
+To compile the qch file for each module, first enter the output directory that
+contains the .qhp file and generate the QCH file.
+
+    $> cd qtbase/doc/qtdoc              #the default path for QT_INSTALL_DOCS for qtdoc
+    $> qhelpgenerator qtdoc.qhp         #creates the QCH file called qtdoc.qch
+
+The QCH file can then be loaded in Qt Assistant or Qt Creator. For Qt Assistant,
+the QCH file can be registered to automatically load it.
+
+    $> assistant -register qtdoc.qch    #to automatically load the documentation
+
+
+Global Files
+============
+
+The qtbase/doc/global directory contains various files used by the modules to
+build the documentation. These include macros, stylesheets, and images for
+displaying documentation.
+
+To include these files in a qdocconf, add the following to a qdocconf file:
+
+    include($QT_INSTALL_DOCS/global/qt-module-defaults.qdocconf)
+
+
+Documentation Structure
+=======================
+For a typical module, the documentation will reside in the source directory.
+The examples and the example documentation are in the "examples" directory.
+
+    qtbase/src/sql/doc/src              #Qt SQL's documentation
+    qtbase/examples/sql                 #Qt SQL's examples
+
+More Information
+================
+
+For more information about Qt 5's documentation, refer to the Qt Project wiki:
+http://qt-project.org/wiki/Qt5DocumentationProject
-- 
cgit v1.2.3