README

To Generate Qt Documentation:

qtdoc contains the main Qt Reference Documentation, which includes
overviews, Qt topics, and examples not specific to any Qt module.The
configuration files are located in qtdoc/doc/config and the articles in
qtdoc/doc/src. Note that QDoc is located in qttools/src/qdoc.

The instructions in this file assumes that the prerequisite binaries are
compiled and in the $PATH variable.

Prerequisites:
    * qtbase exists
    * "qdoc" built and installed
    * other Qt repositories exist as needed

The Qt Reference Documentation was written with links to the released modules
for Qt. If the modules and repositories do not exist, then the resulting HTML
files will contain broken links.

There are two ways to build the documentation. One way is to compile the
documentation using QDoc and the configuration file (qdocconf) file. The other
way is to use CMake and Ninja by running "ninja docs".

Section 1 Building the qdocconf File

    This method is useful for building separate projects without any
    dependencies to other projects.

    To build using the qdocconf file, run the "qdoc" binary and pass the
    qdocconf file as a parameter. "qdoc" is found in qttools repository. 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.

Section 2 Building using CMake and Ninja

    QMake uses the QT_INSTALL_DOCS variable to determine where the documentation
    for Qt is installed. This method is useful for linking to other Qt modules.

    To see where the documentation will be installed, run:
    $> <Qt-installation-dir>/bin/qtpaths -query QT_INSTALL_DOCS

    To generate the documentation, run:

    $> cd qtdoc  #or whichever repository's root
    $> <Qt-installation-dir>/bin/qt-configure-module .
    $> ninja docs
    $> ninja install

    This procedure also works in the top-level Qt repository. Running the
    commands there will generate the documentation for Qt and install them to
    the path set to the QT_INSTALL_DOCS variable.

Section 3 Building Qt Documentation

    To build the Qt module documentation along with the Qt Reference Documentation,
    run the following:

    $> cd qt           # the top-level Qt repository
    $> configure       # creates the build system for all repositories
    $> ninja docs

    To generate only HTML files, run "ninja html_docs" instead of "ninja docs".

Section 4 Packaging the Documentation

    Required binaries:
    * qhelpgenerator - found in qttools

    To compile the qch file for each module, first enter the output directory
    which 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

    Alternatively, modules have a "qch_docs" target:
    $> cd qtbase
    $> make qch_docs #builds the QCH files for modules in qtbase

    The QCH file can then be loaded in Qt Creator.

Section 5 More Information

For more information about Qt's documentation, refer to the Qt Project wiki:
https://wiki.qt.io/Qt_Writing_Guidelines