Building Qt Documentation: Difference between revisions

From Qt Wiki
Jump to navigation Jump to search
No edit summary
(Another relevant category)
(10 intermediate revisions by 6 users not shown)
Line 1: Line 1:
'''English''' [[Building_Qt_Documentation_Russian|Русский]] [[Building_Qt_Documentation_Italian|Italiano]] [[Building_Qt_Documentation_Spanish|Spanish]] [[Building_Qt_Documentation_Japanese|日本語]] [[Building_Qt_Documentation_SimplifiedChinese|简体中文]] [[Building_Qt_Documentation_Korean|한국어]]
[[Category:Developing Qt::Documentation]]
[[Category:Tools]]
{{LangSwitch}}
'''Note:''' For information about writing documentation for Qt, see the [[Writing Qt Documentation]] page. For help on troubleshooting documentation builds, see the [[Troubleshooting Qt Documentation]] page.


[toc align_right="yes" depth="3"]


= Building Qt Documentation =
QDoc (''qdoc'' command in qtbase) builds the documentation and is included in standard Qt 5 installations. The official Qt documentation is built using Linux based machines, requiring libraries needed for [[Building_Qt_5_from_Git | building Qt 5]] and tested on the [http://doc.qt.io/qt-5.0/qtdoc/supported-platforms.html supported desktop platforms].


For information about writing documentation for Qt, see the [[Writing_Qt_Documentation|Writing Qt Documentation]] page.
== Required reading ==
 
For help on troubleshooting documentation builds, see the [[Troubleshooting_Qt_Documentation|Troubleshooting Qt Documentation]] page.
 
= Building Qt 5 Documentation =
 
QDoc (''qdoc'' command in qtbase) builds the documentation and is included in standard Qt 5 installations. The official Qt documentation is built using Linux based machines, requiring libraries needed for [[Building_Qt_5_from_Git | building Qt 5]] and tested on the "supported desktop platforms":http://doc.qt.io/qt-5.0/qtdoc/supported-platforms.html.
 
=== Required reading ===


* [[Get_The_Source | Get the Source Code]] - download the Qt sources
* [[Get_The_Source | Get the Source Code]] - download the Qt sources
Line 24: Line 18:
</code>
</code>


In many cases, building Qt 5 and submodules is not necessary. To build the documentation, it is necessary to build QDoc in qtbase and run ''qmake_all'' in each repository before running ''make docs''
In many cases, building all of Qt 5 is not necessary. To build the documentation, it is necessary to build QDoc (to generate HTML documentation) and qhelpgenerator (to package the HTML documentation into .qch files). These are both located in the qttools repository.
 
QDoc and qhelpgenerator depend on several Qt modules from qtbase. After the configuration step, build qtbase:
 
<code>
cd qt5/qtbase
make
</code>
 
Additionally, QDoc depends on the QML DevTools library from qtdeclarative:
 
<code>
cd qt5/qtdeclarative/src
make sub-qmldevtools
</code>
 
To build the documentation tools:
<code>
cd qt5/qttools/src
make sub-qdoc
</code>
 
If only HTML documentation is needed, the step below, building qhelpgenerator is not required.


To do so after the configure step:
<code>
<code>
cd qt5/qtbase/src
cd qt5/qttools/src/assistant
make sub-qdoc #to build the qdoc binary
make sub-qhelpgenerator
cd qt5/qttools
</code>
make #to build the qhelpgenerator
 
To now build the documentation:
<code>
cd qt5/
cd qt5/
make docs
make qmake_all          # needed on Qt configured for prefix build to update the per-module index directories
make docs               # or just make html_docs if only HTML documentation is needed
</code>
</code>
On Windows, you may use the native ''nmake'' tool, instead. Note that qhelpgenerator has other dependencies in qtbase, therefore, it is best to compile qtbase before building qttools.


Alternatively, "make html_docs" will only build the HTML files and will not create a qch package.
On Windows, you may use the native ''nmake'' tool, instead.
 
 
=== Shadow builds ===


For shadow builds, the source directory and install directories are different and the global templates need to be moved to the install directories. To do so, run:
For shadow builds, the source directory and install directories are different and the global templates need to be moved to the install directories. To do so, run:

Revision as of 13:49, 22 November 2016

En Ar Bg De El Es Fa Fi Fr Hi Hu It Ja Kn Ko Ms Nl Pl Pt Ru Sq Th Tr Uk Zh

Note: For information about writing documentation for Qt, see the Writing Qt Documentation page. For help on troubleshooting documentation builds, see the Troubleshooting Qt Documentation page.


QDoc (qdoc command in qtbase) builds the documentation and is included in standard Qt 5 installations. The official Qt documentation is built using Linux based machines, requiring libraries needed for building Qt 5 and tested on the supported desktop platforms.

Required reading

For the standard installation of the Qt 5 repository (qt5.git), once Qt is built and installed, running make docs in the command line will build QDoc and the Qt 5 documentation set. The output will be located in qt5/qtbase/doc/ or to the directory set to qmake's QT_INSTALL_DOCS variable.

cd qt5/
make docs

In many cases, building all of Qt 5 is not necessary. To build the documentation, it is necessary to build QDoc (to generate HTML documentation) and qhelpgenerator (to package the HTML documentation into .qch files). These are both located in the qttools repository.

QDoc and qhelpgenerator depend on several Qt modules from qtbase. After the configuration step, build qtbase:

cd qt5/qtbase
make

Additionally, QDoc depends on the QML DevTools library from qtdeclarative:

cd qt5/qtdeclarative/src
make sub-qmldevtools

To build the documentation tools:

cd qt5/qttools/src
make sub-qdoc

If only HTML documentation is needed, the step below, building qhelpgenerator is not required.

cd qt5/qttools/src/assistant
make sub-qhelpgenerator

To now build the documentation:

cd qt5/
make qmake_all          # needed on Qt configured for prefix build to update the per-module index directories
make docs               # or just make html_docs if only HTML documentation is needed

On Windows, you may use the native nmake tool, instead.


Shadow builds

For shadow builds, the source directory and install directories are different and the global templates need to be moved to the install directories. To do so, run:

cd qtbase
make install_global_docs

Building the Module Documentation

The Qt modules have their documentation built by running make docs in the command line once Qt 5 is built and installed.

cd qt3d
make docs

Running qdoc Directly

QDoc builds are specified in qdocconf files which tells QDoc where to look and how to set up documentation. To run QDoc, pass the qdocconf file and the output directory as arguments.

qdoc qt3d.qdocconf -outputdir html

Modularized Documentation

The modules have a qdocconf file in the src directory. The Qt_Documentation_Structure page has more information.

Building Qt4 Documentation

Build Qt as normal.

Define environment variables for QT_SOURCE_TREE and for QT_BUILD_TREE appropriately. Make sure the PATH environment variable points to the bin directory containing the qdoc3 executable.

cd path/to/qt
make docs

For the online docs it may be necessary to use

cd path/to/qt
make online_docs

for later versions of Qt.

For Windows™ use the nmake utility instead of make. Some Linux systems will require gmake instead of make.

If you already have Qt compiled (from the SDK, for example) and want to build some special flavour of the doc, you can call directly qdoc3 (QT_SOURCE_TREE, QT_BUILD_TREE, and QTDIR must be set appropriately), here for DITA output:

cd qt-src
bin/qdoc3 tools/qdoc3/test/qt-ditaxml.qdocconf