ECMGenerateQDocΒΆ

This module provides the ecm_generate_qdoc function for generating API documentation files for projects based on qdoc.

It allows to generate both online HTML documentation as well as (installed) QCH files.

ecm_generate_qdoc(<target_name> <qdocconf_file>)

target_name is the library target for which the documentation is generated.

qdocconf_file is the .qdocconf file that controls the documentation generation.

If the project contains multiple libraries with documented APIs ecm_generate_qdoc should be called for each one.

Example usage:

ecm_add_qch(KF6::CoreAddons kcoreaddons.qdocconf)

Documentation is not built as part of the normal build, it needs to be explicity invoked using the following build targets:

  • prepare_docs runs the prepare step from qdoc, which processes sources and creates index files

  • generate_docs runs the generate step from qdoc, generating the final documentation from the index files

  • install_html_docs installs the generated HTML documentation into KDE_INSTALL_QTQCHDIR from KDEInstallDirs

  • generate_qch creates QCH files out of the HTML documentation

  • install_qch_docs installs the QCH files into KDE_INSTALL_QTQCHDIR from KDEInstallDirs

The following global parameters are understood:

  • QDOC_BIN: This can be used to select another qdoc executable than the one found by find_package. This is useful to test with different versions of the qdoc tool.

  • DOC_DESTDIR: This is where the HTML and index files will be generated. This is useful to aggregate results from multiple projects into a single directory.

When combining documentation from multiple projects the recommended procedure is to use a common DOC_DESTDIR and run the prepare stage for all before running the generate stage for all. This ensures that the index files are all available during the generate phase and cross-linking works as expected.

Since 6.11.0.