Re: Updating the Framework apidocs part 1: fixing the presentation
- Date: Fri, 29 Mar 2019 22:00:27 +1300
- From: Ben Cooksley <bcooksley@xxxxxxx>
- Subject: Re: Updating the Framework apidocs part 1: fixing the presentation
On Fri, Mar 29, 2019 at 9:47 PM Juan Carlos Torres <jucato@xxxxxxxxxxx> wrote:
> Hello everyone!
> It's that docs guy again! Hope you don't mind this brief interruption of coding activities to give our apidocs some TLC.
> I recently went over the KDE Frameworks apidocs, one framework and class at a time, to get an overview of what we're facing. And, to be honest, there's quite a lot to be done but we can probably already start with the lowest hanging fruit: the presentation/style. There are three things that seem to be off with the current design that we're using (I'll be filing bug reports as well):
> - All the class names at the top of their respective pages only show the Framework name. For example, instead of showing "KAboutData", it displays "KCoreAddons" only. 
> - The table-based layout for parameters/returns and their descriptions are too narrow and run into each other. 
> - The headers of Deprecated and Todo pages (of frameworks that have them) are unreadable. 
> Probably small stuff but enough to get started on making the apidocs look professional. On that note, is there someone I need to get in touch with about the design of the apidocs? ECM, for example, looks totally out of place.
>From my understanding ECM has a totally separate and different system
for generating it's API Documentation (because Doxygen can't handle
CMake files I believe) which is why it looks totally different.
> I'd love to hear your thoughts and suggestions on the current state of our Frameworks apidocs and how we can make them even better than before. I'm also on IRC (Jucato) and Matrix (also Jucato), though do note I live on UTC+8.
> 1. https://api.kde.org/frameworks/kcoreaddons/html/classKAboutData.html
> 2. https://api.kde.org/frameworks/attica/html/classAttica_1_1AccountBalance.html#a71c29c3638accbd6216be60b08509b76
> 3. https://api.kde.org/frameworks/karchive/html/deprecated.html
> Juan Carlos Torres