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

[Friedrich W. H. Kossebau]

Am Montag, 1. August 2016, 20:59:03 CEST schrieb Olivier Churlaud:
> 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)

Right. I sense more context perhaps is needed than I presumed, to find us 
better aligned. So a few pages back: AFAIK the old apidox generation script 
processed things on a module-base, e.g. all of kde-runtime. It would walk 
through the directories and group things by the Mainpage.dox that it finds 
there, with each Mainpage.dox found defining a new level in the created 
structure. E.g. in kde-runtime there are Mainpage.dox files on these places:
./Mainpage.dox
./kcmshell/Mainpage.dox
./knotify/Mainpage.dox
./plasma/Mainpage.dox
./plasma/declarativeimports/plasmacomponents/Mainpage.dox
./plasma/declarativeimports/core/Mainpage.dox
./plasma/declarativeimports/draganddrop/Mainpage.dox
./plasma/declarativeimports/plasmaextracomponents/Mainpage.dox
./plasma/declarativeimports/qtextracomponents/Mainpage.dox

Which then results in a grouping structure like this on https://api.kde.org/
4.x-api/kde-runtime-apidocs/index.html
    KCMShell
    KNotify
    Plasma Runtime
        PlasmaCore
        DragAndDrop
        PlasmaComponents
        PlasmaExtraComponents
        QtExtraComponents

This approach had a few disadvantages, like forcing the sources directory 
structure to follow the API dox struture. And the apidox-generating scripts 
having no idea about the semantics of that grouping.

Now, IIUC the new metainfo.yaml-based approach by kapidox does not derive the 
structure how to group things from the placement of Mainpage.dox files in the 
repository. Instead it has some grouping semantics defined in the spec of 
metainfo.yaml files ("group", "subgroup", "lib") and developers would describe 
the organizational structure of the product independent of the actual layout 
of the sources. Which IMHO is a good thing and great improvement.
So far on the same page? Or one of us on a different? :)

And now let's get to the page/point where the suggestions for further 
development of kapidox/metainfo.yaml spec are made:
As with any defined semantics/ontologies, they need to be adapted when reality 
shows more variety :)
For one let's look at the example above and see how there are different groups 
of components. One could select e.g. "PlasmaExtraComponents", and the pages 
generated by doxygen would only be about classes belonging to that scope, see 
e.g. "Class List".
Such a sub-library grouping though is not yet defined in metainfo.yaml AFAIK. 
And while the manually maintained README.md and Mainpage.dox files in the 
plasma-framework try to help with getting that grouping of components, the 
pages generated from doxygen do not and e.g. in "Class List" list each and 
every class of "Plasma Frameworks", see https://api.kde.org/frameworks/plasma-framework/html/index.html
So perhaps some optional module structure semantics could be added to the 
metainfo.yaml spec, to allow definitions of sub-library granularity.

You wonder, this was not yet about C++ vs. QML? Indeed. Just, in the old 
script world, the very same Mainpage.dox placement approach used for 
separating sub-library components might have also be used to solve separating 
C++ class documentation and QML type documentation for things coming with the 
same library. Too bad there seems no good example in the old world, at least 
for Plasma the-framework-not-the-desktop the C++-library was in kdelibs, while 
the QML items were in kde-runtime, so already split by that documentation-
wise.
And when again we have a look at the current kapidox-generated docs for KF5 
Plasma Framework, we see that all QML items and C++ are grouped together in 
the generated pages.
To solve that, this could again perhaps be done by extending the metainfo.yaml 
spec, to allow specifying what interface "languages" are supported by a lib 
and from which sources the documentation for a certain language should be 
done.
Knowing about the "language" should help tp improve the documentation 
generation and presentation on api.kde.org, so much better than Mainpage.dox-
based hacks.

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

"Too many clicks" might depend on the starting point :) But does one not 
somewhere have to tell/choose (=click) whether to go for e.g. the QML or the C
++ API? Sane defaults at proper places could spare the additional click for 
most though.

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

Looking at Plasma Frameworks and how QML types and C++ classes are mixed 
together, as user of api.kde.org I have to disagree now, sorry :)

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

Hm, what would be an alternative layout? "use our CMake macro described here", 
"our QML library described there" - where is that "here" and "there? 
Those info bits would be also on api.kde.org. In which organizational 
structure would it be presented, what do you think of?

> What I would propose is that we maybe have a discussion about that
> during Akademy?

While I might not make it there, I hope to see you doing a BoF on api.kde.org 
at Akademy, there should be more of us interested in enabling external people 
(well, and ourselves) to also use our developer-oriented KDE products - after 
all we are trying hard to make these "shared" libraries, my dear fellow KDE 
developers, so let's have more people working on that last mile of API 
documentation now and then! Join and support Olivier! :) 

Cheers
Friedrich