740ff1b881
In clangqdoc, we no longer define platform-specific macros, because they make clang try to include too much include stuff. Instead, when we have something like #if defined(Q_OS_XXX) surrounding something we want clangqdoc to see, we add the Q_CLANG_QDOC macro like this: #if defined(Q_OS_XXX) || defined(Q_CLANG_QDOC). This should not be done everywhere Q_OS_XXX is used, but only where there is some platform-specific things we want to document. Change-Id: I97bb57e9b0c044899fa45b0beb02702906d5c89a Reviewed-by: Martin Smith <martin.smith@qt.io> |
||
---|---|---|
.. | ||
global | ||
src | ||
doc.pro | ||
README |
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