QDoc produces empty directory

[Mark81]

I'm trying to generate my first QDoc output. To test it, right now I have only one comment in main.cpp:

/*!
 * \brief main
 * \param argc
 * \param argv
 * \return
 *
 * bla bla bla
 */

int main(int argc, char *argv[])
{
    // ...

Here my config file:

#include(compat.qdocconf)
#include(fileextensions.qdocconf)
project = MyProject
outputdir   = docs
outputformats = HTML
headerdirs  = .
sourcedirs  = .
exampledirs = .
imagedirs   = ./images

1. in the minimum example the project field is not present. But without it, running qdoc myproject.qdocconf I get:

qt.qdoc: "qdoc can't run; no project set in qdocconf file"

2. with the project field set, this is the output:

qt.qdoc: Start qdoc for MyProject in dual process mode: generate phase.
qt.qdoc: No include paths passed to qdoc; guessing reasonable include paths
(qdoc) Could not find the module header in include paths for module "MyProject" (include paths: QList() )
Artificial module header built from header dirs in qdocconf file
qt.qdoc: Parse source files for "MyProject"
qt.qdoc: Source files parsed for "MyProject"
qt.qdoc: End qdoc for MyProject in dual process mode: generate phase.

I'm not sure how to include paths. Here I cannot find such an include command. It creates the output docs directory but it's almost empty: just the myproject.index file is there.

What I have to do further to produce the HTML files?

[sierdzio]

qdoc is considered to be an internal tool of Qt, it is only intended to generate Qt documentation.

If you want to generate docs for your project, use doxygen instead. It is considered the standard tool for documenting Qt projects. Uses the same syntax as qdoc.

[Mark81]

Ah ok, it should be stated more clear in the documentation... it seems a "built-in" tool to create documentation for Qt-based projects.

[sierdzio]

You're right, it can be confusing!

[paulwicking]

@sierdzio said in QDoc produces empty directory:

qdoc is considered to be an internal tool of Qt, it is only intended to generate Qt documentation.

As this was thread was just brought to my attention, I'll respond here despite the thread being quite old: this statement is incorrect. QDoc is used for a range of projects outside of Qt and has been used by several commercial customers for a long time. As per an announcement at KDE Akademy yesterday, KDE's API documentation is now generated by QDoc.

@Mark81 said in QDoc produces empty directory:

I'm not sure how to include paths.

You must pass the correct include paths when invoking QDoc. Under the hood, QDoc interfaces with Clang, and if Clang doesn't know the existence of types, you get errors. They cascade. The easiest way to do this is integrate QDoc with your build system, unfortunately, Qt doesn't provide a user facing CMake API for this (yet, anyway, there's an open task for it on bugreports). You can find an example of how you can have CMake generate and pass the correct include paths if you look at https://code.qt.io/cgit/qt/qttools.git/tree/src/qdoc/qdoc/tests/validateqdocoutputfiles/CMakeLists.txt#n25:

• On line 25; set an output path for the file. Lines 30-39: Extract Qt include paths and framework paths.
• Line 41 gets the target's include directories (here, for the test), and line 42 generates a file called qdocincludepaths.inc.
• Then pass that file (through its output path) to the qdoc invocation as an "at-file"; e.g. qdoc -outputdir /some/path @/path/to/qdocincludepaths.inc mydocconfig.qdocconf

The include path requirement exists because QDoc needs to understand your actual code structure to generate meaningful documentation. The CMake approach handles this automatically, and that's why we use this in our CI tests.