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
