The future of KApiDox
Hello there,
I’ve been working hard to enhance KApiDox. I’d like to come back on what it is for, what I did and what I see for its future.
Tl;dr
I created a new branch in the KApiDox repository [1] and it’s currently in review on ReviewBoard [2].
Please review it, and if you have the corresponding rights, give me the green lights do put what I did in production. I think it will help KDE products to be more visible on the web. To know more, do read what follows. đŸ™‚
What is KApiDox
KApiDox is part of the KDE Frameworks. As Aurélien Gateau wrote [3]:
KApiDox is a set of tools used to generate KDE Frameworks documentation. These command-line tools use Doxygen to do most of the work.
Currently you can use two tools: kgenapidox, to generate the documentation of a single framework and kgenframeworksapidox, to generate the documentations of all frameworks as well as the landing page which lets you list and filter frameworks by supported platforms.
You can see it working on [4].
Oh, and by the way, it’s written in Python.
What do I propose instead
The Frameworks are the only set of libraries that have a sort of visibility on the web. If other products, like say KDevelop or libkdegames, have public libraries, there is no easy way to generate the documentation and put it on the website.
Global idea
You already got it: the idea is to improve and correct what I pointed above. The new KApiDox would be one tool, that would be run over a set of repositories. It would read recursively all folders and look for CMakeLists.txt and metainfo.yml files. I’ll speak about the latter below.
The libraries are then organized in:
- products: it can be a group like KDE Frameworks, Calligra, KDevelop… or a single library like KIPI,…
- subgroups: Tier 1, Tier 2, …, Krita, …
- libraries: KApiDox, KArchive, ….
A nice landing page is automatically created, then subpages and the documentation. You can see an example in the tar.gz file attached to my review [2].
How can it be used by your projects?
The documentation of your projects can be generated if they provide a metainfo.yml file.
The minimal syntax, for an independent library is:
# metainfo.yml description: Library doing X maintainer: ochurlaud public_lib: true # This is the only mandatory key, don't forget it! logo: path/to/logo.png
This would be understood as a product consisting in one library, which name is read from the CMakeLists.txt.
It’s a little more complex if you want to have groups and subgroups, you can add a lot of other keys (to define the group description, where the sources are, where is the internal documentation…) that are presented in the metainfo_syntax.md file [5] at the root of the repository (in the branch olivier/generate_all_repos).
The future
Since I don’t have the green light to actually use the KApiDox scripts, I don’t want to spend too much time on it, in case my proposition is refused. But I have ideas to go further.
- The tool can easily figure out if it is run over only one product or several or one library.. So the landing page could be different for each scenario.
- People told me that having different version available (like Qt does for the versions 4.8 and 5.x) would be a great plus. It’s quite easy if I teach KApiDox some git commands….
- KApiDox is designed to run only over public libraries (if the key public_lib is not true or not set the library is ignored). An argument could be used to generate as well the private libraries so that developers can use it for themselves.
- KApiDox can currently only work in our infrastructure. If it is supposed to be part of the KDE Framework, it should be usable by other people, out of the community. This means refactoring the code a little and putting what is only part of KDE in another place.
- …
Please review!
Now that you have a rough idea of what I propose, if you find it useful, please tell it, and review my works so that it can be used as soon as possible! The link is there: [2].
Links
[1] KApiDox on Quickgit (think to select the correct branch: olivier/generate_all_repos)
[2] Review on ReviewBoard
[3] AurĂ©lien’s post
[4] API documentation generated by KApiDox
[5] metainfo_syntax.md