Skip to content
  • Categories
  • Recent
  • Tags
  • Popular
  • Users
  • Groups
  • Search
  • Get Qt Extensions
  • Unsolved
Collapse
Brand Logo
  1. Home
  2. Qt Development
  3. Qt Creator and other tools
  4. QDoc does not produce documentation, only a .index file
Forum Update on Monday, May 27th 2025

QDoc does not produce documentation, only a .index file

Scheduled Pinned Locked Moved Unsolved Qt Creator and other tools
4 Posts 2 Posters 195 Views
  • Oldest to Newest
  • Newest to Oldest
  • Most Votes
Reply
  • Reply as topic
Log in to reply
This topic has been deleted. Only users with topic management privileges can see it.
  • G Offline
    G Offline
    greggs
    wrote on 24 Jan 2025, 18:58 last edited by
    #1

    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!

    1 Reply Last reply
    0
    • S Offline
      S Offline
      SGaist
      Lifetime Qt Champion
      wrote on 24 Jan 2025, 19:29 last edited by
      #2

      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.

      Interested in AI ? www.idiap.ch
      Please read the Qt Code of Conduct - https://forum.qt.io/topic/113070/qt-code-of-conduct

      G 1 Reply Last reply 25 Jan 2025, 10:41
      0
      • S SGaist
        24 Jan 2025, 19:29

        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.

        G Offline
        G Offline
        greggs
        wrote on 25 Jan 2025, 10:41 last edited by
        #3

        @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.

        1 Reply Last reply
        0
        • S Offline
          S Offline
          SGaist
          Lifetime Qt Champion
          wrote on 31 Jan 2025, 20:17 last edited by
          #4

          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.

          Interested in AI ? www.idiap.ch
          Please read the Qt Code of Conduct - https://forum.qt.io/topic/113070/qt-code-of-conduct

          1 Reply Last reply
          0

          3/4

          25 Jan 2025, 10:41

          • Login

          • Login or register to search.
          3 out of 4
          • First post
            3/4
            Last post
          0
          • Categories
          • Recent
          • Tags
          • Popular
          • Users
          • Groups
          • Search
          • Get Qt Extensions
          • Unsolved