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

[Olivier Churlaud]

Le 02/08/2016 à 02:59, Friedrich W. H. Kossebau a écrit :
> 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?
"here" and "there" would be only links to the classes.

>
>> 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
Ok, I think this cannot be solved easily with an email discussion. 
Akademy would be better of course. Additionally I don't see how the 
entry point would be in the documentation, so I cannot propose something 
easily to discuss and incrementally improve.

Cheers
Olivier