Qt Quick/QML + Python documentation is not easily discoverable and is lacking

I believe that Python + QML make a very good pair on paper but this pair is a bit put at a disadvantage by the documentation.

To add some context, I'd say that I am an experienced QML & C++ developer (> 10 years experience with both) but when I wanted to try PySide with QML for a new small project I was a bit lost. Hadn't I not have my previous experience, I wouldn't know what I should search for and would have more likely thrown the towel.

Why I think Python and QML makes a good pair (compared to Python + QWidgets):
It greatly reduces the surface of Qt specific Python code the user needs to know.
Learn about QAbstractItemModel, QString and a couple more QtCore classes.
Learn how to integrate Python and QML by exposing classes, properties, functions and signals and you are done.
Well you just need to learn Qt Quick with QML now, but the documentation already exists and doesn't have to be auto-converted from the C++ documentation.

What I find confusing about the actual state about the QML documentation in PySide:

• the Qt for Python landing page doesn't even mention it
• the Getting Started is a "Compiling from Source" guide. There's a note about it but it is still disorienting. Why not rename it instead of adding a note acknowledging the issue? I don't feel like this guide should be as prominent as it is (it isn't in the c++ doc). PS: while writing this issue, I kept clicking on it by mistake while wanting to go to the Quick Start page
• the more useful Quick Start page, does talk about Qt Quick but it is shown after Widgets, not that important but I feel like a small paragraph mentioning the two before jumping straight to Widgets would help raise QML awareness.
• the QML example in the page above doesn't do it justice, showing QML jammed in a string, something not reflecting actual practices and also preventing the pictured code to have syntax highlighting. This issue is acknowledge twice while the fix is arguably simpler. Show the code in a separate file and use engine.load('Main.qml') instead of engine.loadData(QML.encode('utf-8')). While load is not perfect (vs loadFromModule) it would be simple enough.
• the QML example also doesn't show a screenshot contrary to the QWidgets example. The same can be said in the following Qt, QML, Widgets…What Is The Difference? page. The accompanying paragraph paints QML as a bit toy like and too focused around mobile. Qt Quick Controls in Qt 6 can easily render the same themed windows as those shown the QWidgets paragraph.

The above are details but the biggest problem with the PySide documentation is that there is no actual guide. It's made with tutorials and examples partially showing how to do things, and not always in the good way.

The C++ side has a comprehensive Overview - QML and C++ Integration, the Python side hasn't.

Instead there is a "Your First QtQuick/QML Application" tutorial using QWidgets' QApplication and QQuickView instead of QGuiApplication and QQmlApplicationEngine.
The following Python-QML integration tutorial is very limited and doesn't give links for further exploration. Its actual code is very hard to reason around and not something that you would use. What's with those convoluted RadioButton.onToggled? The strength of QML is property bindings but there is no mention of properties here and the possibility to expose them. If you want to show relatable code, what about exposing a simple TrafficLight class, with a color property and a cycle() slot?

The reader is left with no knowledge about properties, signals, models. There's no exhaustive list of what is possible to be exposed.
The following links were very valuable when I started QML years ago:

• Exposing Attributes of C++ Types to QML
• Defining QML Types from C++
• Data Type Conversion Between QML and C++
• Using C++ Models with Qt Quick Views (with its backlink in Models and Views in Qt Quick

I feel that without counterpart for those, the Python QML integration is not reasonably discoverable and insufficiently documented.

As for the reference documentation:

• The PySide6.QtQml module page is full of c++ mentions (ditto for PySide6.QtQuick).
• It has no link to Property, Signal or Slot. Those are buried deep in the QtCore module.

I hope this doesn't read too much as a rambling, I would gladly discuss the above further if needed to improve the Qt ecosystem.