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
