QML QDoc: inheritance, import statement and qmlmodule

[The friendly stranger]

Hi everyone,

I made a library of QML controls with Visual Studio 2019 (so I am not using Qt Creator).
I want to make a documentation with the QDoc. I am able to generate a documentation that works but I still have some issues.

• I want to display the "inherits" and "inherited by" like QtQuick does:

This works fine if I only use controls from my library (MyItem1 and MyItem2). However, there is no display if the parent is a QtQuick control (Item.qml, Rectangle.qml...). Nothing changes if I use \inherits and QtQuick namespace (ex: QtQuick::Item). Any idea what the problem is ?

• I want to display the Import Statement like any control in the qml documentation. Unfortunnately, the import is weird (see below)
  
  I just don't know how to handle this part. I understand I may have to use qdoc and define a qmlmodule. But I don't know how to link my qdoc to my qdocconfig. I don't have any error nor result in the doc. I have the feeling that I'll have to make a .pro file but I don't use QtCreator...

Below a minimal version of my code:

DocQML.qdocconf

include($QTDIR/doc/global/compat.qdocconf)
include($QTDIR/doc/global/qt-cpp-defines.qdocconf)

project = MyProject
version = 1.0.0.0
description = Documentation for my controls.

sourcedirs = ../qml/
headerdirs = ../qml/
imagedirs = .

sources.fileextensions = "*.qdoc *.qml"

outputdir  =    ./doc/qml/
outputformats = HTML

HTML.stylesheets = style.css
HTML.headerstyles = "<link rel=\"stylesheet\" type=\"text/css\" href=\"style/style.css\"/>\n"

mymodule.qdoc - This file has no impact on the doc

/*!
    \qmlmodule MyLib 1.0
    \title MyLib 1.0 QML types

    This is my lib
*/

MyItem1 - inheritance doesn't work

import QtQuick 2.10 as QtQuick

/*!
	\qmltype MyItem1
	\inqmlmodule MyLib
	\inherits QtQuick::Item
	A custom item 1. MyLib. MyLib::MyItem2
*/

QtQuick.Item { /* */}

MyItem2 - inheritance works since I use my local control

import QtQuick 2.10  as QtQuick

/*!
	\qmltype MyItem2
	\inqmlmodule MyLib

	 A custom item 2
*/

QtQuick.MyItem1 { /**/}

[raven-worx]

@The-friendly-stranger

import statement

I can confirm that using the following in an arbitrary qdoc file displays a correct import statement in the docs:

/*!
    \qmlmodule My.Module 1.0
    \title My QML module
    \brief Some of my components

    Description of my module
*/

Where did you place mymodule.qdoc? It needs to be inside a folder you referenced in DocQML.qdocconf in sourcedirs. E.g:

sourcedirs += \
     ../qml/ \
     path/to/qdoc/files/

Inherits statement

Since you want to reference / link against Qt types in the docs you are missing the index files which have the necessary doc information for Qt types. In your DocQML.qdocconf add something like this:

indexes += \
      indexes/qtqml.index \
      indexes/qtquick.index \
      indexes/qtquickcontrols.index \
      indexes/qtquickcontrols2.index \
      ... \
      ...

The index files of each module can be found in your Qt installation. E.g. "C:\Qt\Docs\Qt-5.15.2\qtquick\qtquick.index"

[The friendly stranger]

import statement
Aaaah thank you! Of course I need to specify the right path... I put the .qdoc with my .qdocconf but I didn't add the current path to sourcedirs. Now it works well

Inherits statement
Your explanation are very clear but I didn't find any .index in my Qt folder. I went to the doc folder and I only found qdocconf and qdoc files (See the image below).

I also tried to generate a doc with the qt-module-default.qdocconf but I have missing environment variables. I read the documentation about the indexes and found the keyword "depends'' but no success. As you can see on the picture, I use Qt 5.10 with msvc2017.

Thanks again for all your help.

[raven-worx]

@The-friendly-stranger
as i said the index files are for example in "C:\Qt\Docs\Qt-5.12.5\qtquick\qtquick.index"
Where the platform Qt data is in "C:\Qt\5.12.5\msvc2017_64..."

So i guess you are looking the wrong sub folder.
Simply search for "*.index" files in the path containing your Qt MaintainanceTool

[The friendly stranger]

There is no such .index file in the entire Qt folder. I use a binaries version so I am wondering if some files are missing.
Is there any way to get/generate the .html and the .index myself ?

Otherwise, is it possible to use the \inherits with a link ? So I can redirect the users on the Qt webpage.

[raven-worx]

@The-friendly-stranger said in QML QDoc: inheritance, import statement and qmlmodule:

Is there any way to get/generate the .html and the .index myself

build the docs from Qt source yourself
Or use the MaintainanceTool and just download the documentation.

Make sure you call it with MaintenanceTool.exe --show-virtual-components and then just checkmark the documentaion

Otherwise, is it possible to use the \inherits with a link ? So I can redirect the users on the Qt webpage.

thats what the index files are there for.
if you build your docs with an online template you get online ref links, for offline docs (e.g. inside QtCreator) you get ref links there.

[The friendly stranger]

Thanks again for your help! The inheritance works well with the items from QtQuick.
However, I have a corner case with the QtQuickControls module.

Sometimes, my control shares the same name than Qt. For instance, I have my own CheckBox that inherits from Qt CheckBox.

// CheckBox.qml - My slider
import QtQuick 2.10
import QtQuick.Controls 2.3 as QtQuickControls
QtQuickControls.CheckBox {
// ...
}

In this case, I am unable to show the CheckBox parent.

This is weird because I don't have this issue with the QtQuick module. As a test, I made my own Canvas control that inherits from Qt Canvas and I have the right reference.

// Canvas.qml - My canvas
import QtQuick 2.10
Canvas {
// ...
}

I can also make the difference between the 2 Canvas using MyModule::Canvas and QtQuick::Canvas. MyModule::CheckBox works but I didn't find the right namespace for the Qt version. I tried QtQuick/QtQuickControls/QtQuickControls2 with several case combinaisons.

I guess the best advice is not using the same name than Qt but I would like to keep them, if possible.

Once again, thank you very much for all your help.

[The friendly stranger]

I will edit my previous message.

I didn't have the Checkbox inheritance from Qt because I used the modules qtquickcontrols.index and qtquickcontrols2.index at the same time. I guess there was a conflict between these files. Now it works if I only use qtqml.index, qtquick.index and qtquickcontrols2.index.

I still have the issue with the namespace though. I cannot use the CheckBox from QtQuickControls.

Here my current file with the indexes.

project = MyModule
version = 1.0.0.0
description = Documentation for MyModule

sourcedirs = \
	./ \
	../qml/ \
	
headerdirs = ../qml/
imagedirs = .

indexes = \
	Qt/qtqml/qtqml.index \
	Qt/qtquick/qtquick.index \
	Qt/qtquickcontrols2/qtquickcontrols2.index

sources.fileextensions = "*.qml *.qdoc"

outputdir  =    ./generated/
outputformats = HTML

HTML.stylesheets = style.css
HTML.headerstyles = "<link rel=\"stylesheet\" type=\"text/css\" href=\"style/style.css\"/>\n"

[raven-worx]

@The-friendly-stranger
https://doc.qt.io/qt-5/08-qdoc-commands-creatinglinks.html#fixing-ambiguous-links

[The friendly stranger]

Ok I see, I will take a closer look on this. Thank you for all your help. I will mark this discussion as resolved