Building Qt Documentation

From Qt Wiki
Revision as of 20:27, 9 September 2024 by Joger (talk | contribs) (Clarified LLVM_INSTALL_DIR)
Jump to navigation Jump to search

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.

Building Qt 6 Documentation

Note: If you are not familiar with building Qt, or if you need to test new QDoc features, skip this part, and continue from the 'Required reading' section. On the other hand, if you are already familiar with building Qt from the command line and have the Qt source code checked out, and you also have recent Qt installed with the online installer, you can build the documentation as a documentation-only build without building QDoc first.

Documentation only build using a Qt host build

This section assumes that you have checked out Qt and run init-repository as described in Building Qt 6. Note that you don't need to have every submodule checked out, just QtBase and the submodules that you otherwise use when you build Qt.

After creating a new folder for your doc build, configure Qt inside that folder as a documentation-only build. You do this using an installed version of Qt as a host. This way, QDoc from the host is used, and we don't need to build it. The following command line shows an example CMake command, where the source code is located in D:\qt\qt6, and Qt was installed using the online installer under C:\Qt\6.6.0\msvc2019_64. Update the source directory and host path to your own setup before running it: 

cmake D:\qt\qt6 -GNinja -DQT_HOST_PATH=C:\Qt\6.6.0\msvc2019_64 -DQT_NO_PACKAGE_VERSION_CHECK=TRUE -DQT_NO_PACKAGE_VERSION_INCOMPATIBLE_WARNING=TRUE

Note that CMake may complain about failing to build QDoc. This happens if libllvm is not configured. This is not a problem, and the configured build tree can still be used to build the documentation because it uses QDoc from the host path.

Once CMake finishes, do not build all targets using ninja all, just build the documentation targets you need. You can build the documentation for all checked-out submodules by running: 

ninja docs

Typically, developers will only update documentation for a single module at a time. After having built the complete documentation, you can now iterate quickly on the documentation for a single module, for example QtMultimedia, by building only the documentation for this module: 

ninja docs_Multimedia

You can list the available documentation targets with this command on Linux, or Windows with git bash: 

ninja -t targets | grep ^docs

After building the documentation target, the main index.html file for the entire HTML Qt documentation can be found in your build directory under doc/qtdoc/index.html. HTML documentation for other modules can be found in the corresponding directory under the doc folder.

See also Docs: Documentation-only Build and the Qt super repo README.md.

Important: When using CMake, regular Makefile targets are not generated by default. On most platforms in Qt6, ninja is used by default. So, instead of "make docs" you would call "ninja docs" or "ninja html_docs" or "cmake --build . docs", for example.

Required reading

QDoc Build Requirements

Since Qt 6.8, QDoc requires libclang/LLVM/libllvm version >= 17.0. (See also Installing Clang for QDoc). To ensure that the correct version of libclang/LLVM/libllvm is used for building QDoc, set the LLVM_INSTALL_DIR environment variable to its top-level directory which contains the 'bin', 'include', and 'lib' folders. You can download the prebuilt Clang libraries Qt builds QDoc with for a number of platforms from download.qt.io.

Important: If you build on Windows, be aware that libllvm only works with release builds of Qt. Also, ensure that you have the path to libclang/bin in PATH to ensure that the necessary DLLs can be found, or you may see "Exit code 0xc0000135" errors.

Ninja

Building QDoc and the documentation

Checkout the qt5 repository and all its submodules. For the standard installation of the Qt 6 repository (qt/qt5), to build the documentation, it is necessary to build QDoc (to generate HTML documentation), qhelpgenerator (to package the HTML documentation into .qch files) and qtattributionsscanner (looks for json files that document the 3rd party licenses and generates Qdoc files out of that).

In order to be able to build docs in html format, once you have configured everything, run "ninja qdoc qtattributionsscanner".

If you want to package these file so that they can be imported into qtcreator, run "ninja qhelpgenerator".

From the top level directory, run "ninja html_docs" in the command line, the output will be located in the build directory. If you want to then generate the .qch files, run "ninja qch_docs".

Building the Module Documentation

If you wish to build the documents for a specific submodule, run the 'ninja' command together with the name of the file, frm the top-level directory. e.g, To build the Qtcore documents, run "ninja html_docs_Core".

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 and tested on the supported desktop platforms.

Build Requirements

From Qt version 5.11, libclang/LLVM/libllvm is required to build QDoc. The following versions are required (See also Installing Clang for QDoc):

  • On Linux and macOS, use libclang version >= 3.9. The package clang is required on many Linux systems to obtain the required Cmake files.
  • On Windows, use libclang version >= 6.0. The prebuilt libclang from download.qt.io can be used. Note that the prebuilt library is a release build and that qdoc has to be built in release mode too. Further note QTBUG-108391 and that some cmake files might require editing.
  • From Qt version 6, libclang/LLVM/libllvm version >= 10.0 is required.
  • From Qt 6.7, QDoc requires libclang/LLVM version >= 15.0.

If LLVM is not installed or not found in the package tree of your system, QDoc will not be built and you will not be able to build documentation. Once LLVM is installed, the LLVM_INSTALL_DIR environment variable must be set pointing to its top-level installation directory.

Required reading

If the source is obtained via git, ensure that the submodule 

qttools

is checked out. 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

Note however that since Qt 5.11, QDoc uses a Clang-based parser for documenting C++ classes; this requires that also the correct include paths are passed to Clang. QDoc accepts -I<path> command line arguments, just like a compiler does. Additional include paths can be also defined in a .qdocconf file, using the includepaths configuration variable.

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
Retrieved from "https://wiki.qt.io/index.php?title=Building_Qt_Documentation&oldid=42544"