QDoc does not produce documentation, only a .index file

[greggs]

Hello everyone, I'm trying to create some documentation for my projects but I cannot make QDoc work. I have tried in Windows11 and Arch Linux without any success and I would like to know what am I missing. I have created a test project that has some QDoc comments inside. The project is in ~/idk and there is a simple MainWindow.h, MainWindow.cpp and main.cpp. My qdocconf is also in the root of the idk dir and it's set up according to the minimal configuration like:

project = "idk"

headerdirs = /home/greggs/idk

sourcedirs = /home/greggs/idk

outputdir = public

The result is an idk.index file which is a kinda-XML file that is not showing anything like documentation. When I run qdoc I get these:

qt.qdoc: Start qdoc for idk in dual process mode: generate phase.
(qdoc) Could not find the module header in include paths for module "idk"   (include paths:  QVector("-I/home/greggs/idk") )
       Artificial module header built from header dirs in qdocconf file
qt.qdoc: Parse source files for "idk"
qt.qdoc: Source files parsed for "idk"
qt.qdoc: End qdoc for idk in dual process mode: generate phase.

Could someone point out what I am doing wrong? There is no point showing the mainwindow.h and .cpp since there is only a constructor and destructor for testing purposes. Feel free to ask for more info if needed. Much appreciated!

[SGaist]

Hi,

I don't have an example at hand directly but your configuration seems a bit too minimal.

Did you already read the QDoc configuration guide ?

Another source of inspiration is Qt's own sources which also use qdoc.

[greggs]

@SGaist Hello and thanks for your time. Yes I read the guide and according to this I made my configuration file. I agree that it is minimal but it is based on this

# QDoc is a tool that constantly evolves and there may be compatibility issues
# between old and new practices. For that reason, QDoc configuration files in
# the Qt Project includes compat.qdocconf:
#include(compat.qdocconf)

# Give the documentation project a title:
project = My documentation project

# Pass additional include paths to QDoc when parsing C++ code for documentation
# comments.
#includepaths += -I/some/path

# QDoc needs a lists of file extensions to know which files to process in
# different situations. Uncomment the following include statement to get
# a pre-defined list of file extensions.
#include(fileextensions.qdocconf)

# You can also specify file extensions manually.
headers.fileextensions  = "*.h *.hpp"
sources.fileextensions  = "*.cpp *.qml *.qdoc"

# The outputdir variable specifies the directory where QDoc places the generated
# documentation.
outputdir   = public

# The headerdirs variable specifies the directories that contain the header
# files associated with the .cpp source files used in the documentation.
headerdirs  = .

# The sourcedirs variable specifies the directories that contain the .cpp or
# .qdoc files used in the documentation.
sourcedirs  = .

# The exampledirs variable specifies the directories that contain the source
# code of the example files.
exampledirs = ./examples

# The imagedirs variable specifies the directories that contain images used in
# the documentation.
imagedirs   = ./images

# Set a warning limit. QDoc will exit with a non-zero exit code if it generates
# documentation warnings during the documentation build. Useful for tracking
# down documentation issues.
#warninglimit = 0
#warninglimit.enabled = true

I assume that I could create a simple documentation html file with those parameters I have in my config. But I get only a .index file which is not what I expected. Do I have to create html, css and js files that will make the .index file into a proper documentation html file? Because from what I get, including the source and header files is sufficient enough, along with the file extensions and the output directory. I will check QT source code that's a good tip.

[SGaist]

In fact you need multiple things:

• Grouping and / or modules in the documentation of your code
• An "idk.qdoc" file for the main content of the documentation to act as a starting page

I would recommend checking one of the smaller Qt modules. They should have a pretty simple set of documentation files that you can get inspiration from.