kapidox: supporting also QML (and cmake, Python,, ...)

[Olivier Churlaud]

Hi,

I tried to address each point raised here. Don't hesitate to criticize 
or questions my answers and even propose something else. I try to find 
the best solutions but it doesn't mean my solutions are actually the best.

Le 01/08/2016 à 19:50, Friedrich W. H. Kossebau a écrit :
> Hi, Olivier and all,
>
> picking up from the short chat on #plasma today:
>
> so given kapidox is overcoming the old API dox generating scripts with more
> proper semantic info...
> where the old scripts allowed to use random Mainpage.dox at random places in
> the directories to structure the created documentation (e.g. to group QML
> "classes" away from C++ classes), kapidox now would need extension of its
> spec, with semantics needed to talk about QML types and C++ classes to allow
> proper generation of nicely separated pages.
>
> This actually touches a broader problem with the current generated
> documentation, which right now is centric to the C++ interfaces. Though
> existing KDE library products have at least interfaces in
> * C++
> * QML
> * CMake macros [1]
> and perhaps one day bindings in Python and other languages would be also
> provided directly with the products and thus it would be great to have their
> documentation covered as well easily.
Again I would like to remember you that KApidox is just creating a frame 
around our libs, and says "Doxygen, run here, and use theses tags, then 
put the result in this template".
So basically, everything that was possible before, will also be with 
KApidox. The frameworks currently use a README.md as an entry page (to 
be more interfaced with Github?) and most other libraries use a 
Mainpage.dox instead. With the latter it's quite easy to do what 
Friedrich is proposing (cf the Okular example)

In my opinion, what is needed is just that the front page has links to 
the QML/C++/Python/... documentation. Too many layers might make the 
browsing too complex (too many clicks to get to the info).

I'm afraid that looking for the perfect solution is counter productive, 
as nothing would happen until then. However what you raise makes sense: 
I don't have any specifications about which direction to go, so I set 
myself 1 task: generating the whole documentation (qch/man files and 
searching process) with kapidox and only that, in order to cleanup the 
api server.  Every other feature is done while discussing with projects 
coming in.

The system was designed for the Frameworks so it works well for it. 
Phonon had no special needs, and Okular neither. Kirigami is there since 
today as well, and I changed some details to fit their needs. Next will 
be Marble and Okteta.

Each library might have different expectations, and documentation 
ways... I'm afraid we build again an unmanageable piece of program if we 
don't decide how everyone should work (which was the case before it seems).

> [1] E.g. KCoreAddon installs a few cmake macros, like
> kcoreaddons_desktop_to_json, which have nice API dox inside, but there is
> nothing generated from that on api.kde.org currently, both bad for
> discoverability or pointing people to things with urls.
For this specific issue, I think the problem is that the frameworks 
miss, at their whole, high level documentation, as the survey I made 
showed. If we had a more high level doc, that would highlight concepts 
and redirect to the documentation, we wouldn't have to worry about 
discoverability. But again, yes, I think we have some progresses to do 
in our documentation, to allow more people to use our libraries.

> For a solution:
> Perhaps at the generation side there could be another level right below the
> library, for the interface (C++, QML, CMake, ...).
> So "Product" > "Library" > "Interface",
>
> By the example of Plasma Components (https://api.kde.org/frameworks/plasma-framework) there would then be in the header
>      KDE API Reference > The KDE Frameworks > Plasma > QML
>      KDE API Reference > The KDE Frameworks > Plasma > C++
> and in the left sidebar there would be another section "Language" (or better
> term) which would allow to switch to the docs for the other interfaces
> supported (C++, QML, CMake, ...).
To be honest, at the time of writing, I don't find it very good, because 
you don't look for CMake or QML libs. You look for a way to do 
something. In my opinion, the entry page should say "if you need to do 
this, use our CMake macro described here". "If you want to draw this 
type of interaction, our QML library described there is what you need' 
and so on.

Maybe I oversee some use cases because I never really contributed to a 
framework or really use KF5 out of a porting.

What I would propose is that we maybe have a discussion about that 
during Akademy? I hope I'll have cleanup the code base and implemented 
the indexing/search feature so that we can also dig in the code and 
imagine how to make it better.

We really need to define some use cases first, before getting in the 
technical solution.
> On the metainfo.yaml spec side, no idea yet.
>
> Cheers
> Friedrich
Cheers,
Olivier