a9bb1c63dc
it looks nicer this way Change-Id: I872976bdef5f581187a758aa92b02e2f5f32b130 Reviewed-by: Oswald Buddenhagen <oswald.buddenhagen@theqtcompany.com>
110 lines
3.6 KiB
Plaintext
110 lines
3.6 KiB
Plaintext
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://wiki.qt.io/Qt5DocumentationProject
|