Important: Please read the Qt Code of Conduct - https://forum.qt.io/topic/113070/qt-code-of-conduct

Linking to Qt offline documentation with Qdoc



  • Hi,
    I am trying to generate documentation for reusable QML components for a project, but I am having trouble getting the *.qch to link to the Qt offline documentation inside QtCreator

    //HelloButton.qml
    /*!
        \qmltype HelloButton
        \inherits QtQuick::Rectangle
        \brief A Hello World button
    */
    Rectangle
    {
        height: 50
        width: 100
        color: "yellow"
        Text
        {
            anchors.centerIn: parent
            text: "Say Hello"
        }
        MouseArea
        {
            anchors.fill: parent
            onClicked: {console.log("Hello World!")}
        }
    }
    

    Ideally, I'd like to be able to generate documentation that looks like the following inside QtCreator:

    0_1555422326487_eb71719b-020d-4b6b-a5d4-bf1b27027f5a-image.png

    0_1555422348065_3e9f6f33-ff19-46dd-a1aa-07bb6d690595-image.png

    I was able to generate the above documentation by including Qt source files in my qdocconf file. This is not ideal as I am re-generating the Qt documentation. What I'd like to do is link to the already existing offline documentation included with the Qt installation.

    I tried using the "indexes" option in the *.qdocconf, but this links externally to the Qt online documentation, which is not what I want.

    It seems like the "depends" option might be what I'm looking for, but when I do something like depends += qtquickcontrols2 I get the error: qdoc: warning: Dependent modules specified, but no index directories were set. There will probably be errors for missing links. I don't get any linkage to the Qt documentation when I try this.

    Is there any guidance on getting this to work the way I want it to? Thanks!


  • Moderators

    @zhannum
    how does your qdocconf file look like exactly?
    Did you include the offline template?

    include($QTDIR/doc/global/macros.qdocconf) #macros for QDoc commands
    include($QTDIR/doc/global/qt-cpp-defines.qdocconf)
    include($QTDIR/doc/global/compat.qdocconf) #compatibility macros
    include($QTDIR/doc/global/fileextensions.qdocconf)
    include($QTDIR/doc/global/qt-html-templates-offline.qdocconf)
    
    ...
    
    # exact paths left out for simplicity - or copy all index files from QTDIR next to your qdocconf file 
    indexes += \
        indexes/qdoc.index \
        indexes/qt3d.index \
        indexes/qtandroidextras.index \
        indexes/qtbluetooth.index \
        indexes/qtcanvas3d.index \
        indexes/qtconcurrent.index \
        indexes/qtcore.index \
        indexes/qtdoc.index \
        indexes/qtgamepad.index \
        indexes/qtgraphicaleffects.index \
        indexes/qtgui.index \
        indexes/qthelp.index \
        indexes/qtimageformats.index \
        indexes/qtlinguist.index \
        indexes/qtlocation.index \
        indexes/qtmultimedia.index \
        indexes/qtnetwork.index \
        indexes/qtnetworkauth.index \
        indexes/qtnfc.index \
        indexes/qtopengl.index \
        indexes/qtplatformheaders.index \
        indexes/qtpositioning.index \
        indexes/qtqml.index \
        indexes/qtqmltest.index \
        indexes/qtquick.index \
        indexes/qtquickcontrols.index \
        indexes/qtquickcontrols2.index \
        indexes/qtquickdialogs.index \
        indexes/qtquickextras.index \
        indexes/qtremoteobjects.index \
        indexes/qtsensors.index \
        indexes/qtspeech.index \
        indexes/qtsvg.index \
        indexes/qtvirtualkeyboard.index \
        indexes/qtwebchannel.index \
        indexes/qtwebengine.index \
        indexes/qtwebsockets.index \
        indexes/qtwebview.index \
        indexes/qtwidgets.index \
        indexes/qtxml.index \
        indexes/qtxmlpatterns.index
    


  • @raven-worx

    Yes I'm including the default offline template.

    Full qdocconf:

    include($QT_INSTALL_DOCS/global/qt-module-defaults-offline.qdocconf)
    include($QT_INSTALL_DOCS/global/config.qdocconf)
    include($QT_INSTALL_DOCS/global/fileextensions.qdocconf)
    
    project = Hello World
    description = Hello World
    
    sourcedirs += . \
    		 #/home/vagrant/qt-everywhere-src-5.11.3/qtquickcontrols2/src/quickcontrols2 \
    		 #/home/vagrant/qt-everywhere-src-5.11.3/qtquickcontrols2/src/quicktemplates2 \
    		 #/home/vagrant/qt-everywhere-src-5.11.3/qtdeclarative/src/quick \
    
    imagedirs += /home/vagrant/qt-everywhere-src-5.11.3/qtquickcontrols2/src/imports/controls/doc/images \
    
    # depends += qtquickcontrols2
    indexes += 	/home/vagrant/Qt/Docs/Qt-5.11.3/qtquickcontrols2/qtquickcontrols2.index \
    		/home/vagrant/Qt/Docs/Qt-5.11.3/qdoc/qdoc.index \
    		/home/vagrant/Qt/Docs/Qt-5.11.3/qmake/qmake.index \
    		/home/vagrant/Qt/Docs/Qt-5.11.3/qt3d/qt3d.index \
    		/home/vagrant/Qt/Docs/Qt-5.11.3/qtandroidextras/qtandroidextras.index \
    		/home/vagrant/Qt/Docs/Qt-5.11.3/qtassistant/qtassistant.index \
    		/home/vagrant/Qt/Docs/Qt-5.11.3/qtbluetooth/qtbluetooth.index \
    		/home/vagrant/Qt/Docs/Qt-5.11.3/qtcanvas3d/qtcanvas3d.index \
    		/home/vagrant/Qt/Docs/Qt-5.11.3/qtconcurrent/qtconcurrent.index \
    		/home/vagrant/Qt/Docs/Qt-5.11.3/qtcore/qtcore.index \
    		/home/vagrant/Qt/Docs/Qt-5.11.3/qtdbus/qtdbus.index \
    		/home/vagrant/Qt/Docs/Qt-5.11.3/qtdesigner/qtdesigner.index \
    		/home/vagrant/Qt/Docs/Qt-5.11.3/qtdoc/qtdoc.index \
    		/home/vagrant/Qt/Docs/Qt-5.11.3/qtgamepad/qtgamepad.index \
    		/home/vagrant/Qt/Docs/Qt-5.11.3/qtgraphicaleffects/qtgraphicaleffects.index \
    		/home/vagrant/Qt/Docs/Qt-5.11.3/qtgui/qtgui.index \
    		/home/vagrant/Qt/Docs/Qt-5.11.3/qthelp/qthelp.index \
    		/home/vagrant/Qt/Docs/Qt-5.11.3/qtimageformats/qtimageformats.index \
    		/home/vagrant/Qt/Docs/Qt-5.11.3/qtlabscalendar/qtlabscalendar.index \
    		/home/vagrant/Qt/Docs/Qt-5.11.3/qtlabsplatform/qtlabsplatform.index \
    		/home/vagrant/Qt/Docs/Qt-5.11.3/qtlinguist/qtlinguist.index \
    		/home/vagrant/Qt/Docs/Qt-5.11.3/qtlocation/qtlocation.index \
    		/home/vagrant/Qt/Docs/Qt-5.11.3/qtmacextras/qtmacextras.index \
    		/home/vagrant/Qt/Docs/Qt-5.11.3/qtmultimedia/qtmultimedia.index \
    		/home/vagrant/Qt/Docs/Qt-5.11.3/qtnetwork/qtnetwork.index \
    		/home/vagrant/Qt/Docs/Qt-5.11.3/qtnfc/qtnfc.index \
    		/home/vagrant/Qt/Docs/Qt-5.11.3/qtopengl/qtopengl.index \
    		/home/vagrant/Qt/Docs/Qt-5.11.3/qtplatformheaders/qtplatformheaders.index \
    		/home/vagrant/Qt/Docs/Qt-5.11.3/qtpositioning/qtpositioning.index \
    		/home/vagrant/Qt/Docs/Qt-5.11.3/qtprintsupport/qtprintsupport.index \
    		/home/vagrant/Qt/Docs/Qt-5.11.3/qtqml/qtqml.index \
    		/home/vagrant/Qt/Docs/Qt-5.11.3/qtqmltest/qtqmltest.index \
    		/home/vagrant/Qt/Docs/Qt-5.11.3/qtquick/qtquick.index \
    		/home/vagrant/Qt/Docs/Qt-5.11.3/qtquickcontrols/qtquickcontrols.index \
    		/home/vagrant/Qt/Docs/Qt-5.11.3/qtquickdialogs/qtquickdialogs.index \
    		/home/vagrant/Qt/Docs/Qt-5.11.3/qtquickextras/qtquickextras.index \
    		/home/vagrant/Qt/Docs/Qt-5.11.3/qtscxml/qtscxml.index \
    		/home/vagrant/Qt/Docs/Qt-5.11.3/qtsensors/qtsensors.index \
    		/home/vagrant/Qt/Docs/Qt-5.11.3/qtserialbus/qtserialbus.index \
    		/home/vagrant/Qt/Docs/Qt-5.11.3/qtserialport/qtserialport.index \
    		/home/vagrant/Qt/Docs/Qt-5.11.3/qtspeech/qtspeech.index \
    		/home/vagrant/Qt/Docs/Qt-5.11.3/qtsql/qtsql.index \
    		/home/vagrant/Qt/Docs/Qt-5.11.3/qtsvg/qtsvg.index \
    		/home/vagrant/Qt/Docs/Qt-5.11.3/qttestlib/qttestlib.index \
    		/home/vagrant/Qt/Docs/Qt-5.11.3/qtuitools/qtuitools.index \
    		/home/vagrant/Qt/Docs/Qt-5.11.3/qtwaylandcompositor/qtwaylandcompositor.index \
    		/home/vagrant/Qt/Docs/Qt-5.11.3/qtwebchannel/qtwebchannel.index \
    		/home/vagrant/Qt/Docs/Qt-5.11.3/qtwebsockets/qtwebsockets.index \
    		/home/vagrant/Qt/Docs/Qt-5.11.3/qtwebview/qtwebview.index \
    		/home/vagrant/Qt/Docs/Qt-5.11.3/qtwidgets/qtwidgets.index \
    		/home/vagrant/Qt/Docs/Qt-5.11.3/qtwinextras/qtwinextras.index \
    		/home/vagrant/Qt/Docs/Qt-5.11.3/qtx11extras/qtx11extras.index \
    		/home/vagrant/Qt/Docs/Qt-5.11.3/qtxml/qtxml.index \
    		/home/vagrant/Qt/Docs/Qt-5.11.3/qtxmlpatterns/qtxmlpatterns.index \
    
    
    outputdir = ./html
    outputformats = HTML
    
    qhp.projects = HelloWorld
    qhp.HelloWorld.file = helloworld.qhp
    qhp.HelloWorld.indexTitle = HelloWorld
    qhp.HelloWorld.indexRoot = 
    qhp.HelloWorld.virtualfolder = HelloWorld
    qhp.HelloWorld.subprojects = qmltypes
    qhp.HelloWorld.subprojects.qmltypes.selectors = qmltype
    

    This does create a link, but it links to the online documentation, which opens a browser window. In the "List of All Members..." page, it also only shows the first ancestor, instead of all ancestors, which is less than ideal.

    <tr>
    <td class="memItemLeft rightAlign topAlign"> Import Statement:</td>
    <td class="memItemRight bottomAlign"> import  </td></tr>
    <tr><td class="memItemLeft rightAlign topAlign"> Inherits:</td>
    <td class="memItemRight bottomAlign"> 
    <p><a href="http://doc.qt.io/qt-5/qml-qtquick-rectangle.html">Rectangle</a></p>
    ...
    


  • @raven-worx Is there any additional guidance on using the "depends" option?


  • Moderators

    @zhannum
    not that i am aware of
    https://doc.qt.io/qt-5/qtgui-qdocconf.html

    but i think its not really necessary, also its not documented it seems.


Log in to reply