Web lists-archives.com

Re: Updating the Framework apidocs part 1: fixing the presentation

Le vendredi 29 mars 2019, 09:47:34 CET Juan Carlos Torres a écrit :
> Hello everyone!

Hi again!

> 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. [1]
> - The table-based layout for parameters/returns and their descriptions are
> too narrow and run into each other. [2]
> - The headers of Deprecated and Todo pages (of frameworks that have them)
> are unreadable. [3]

I'm the one who is supposed to be in charge of api.kde.org and specially kapidox, the program that generate the website.

I changed a lot of things in the past 5 years to make it more modern and usable. Of course there is still plenty to do, but I don't have the time to do it anymore. I still have the backlog though.

Some things I wanted to do are:
- having more pages of descriptions and explanations in the repos, that would be found and nicely rendered by kapidox
- have the relevant info more foundable
- finish the design overhaul (it's already responsive design!!) : there are some bugs that you spotted that we should fix and we might want to use the kde.org colors and theme.
- continue adding libs (kdevelop etc) there

I worked some times ago on the wiki as well. The goals were the following :
- everything community related should be in community.kde.org. It's an internal wiki for people who contribute or want to.
- techbase should be the entry point for external devs to our products. So we should keep a product oriented structure, and for each product, have links to the website if it exists (for example kdevelop.org), give mailing list à d bug trackers info etc. The tutorials could be moved under the relevant products. And they should be simplified to the use of a given framework on top of Qt, instead of all the kf5 stack. Having the whole KF5 stack let people think it's a all or nothing approach, like in the kde4 time, which is not.

One of the goal of this is to break the idea that kde is a project, and to show that each framework or product can be used without the others, that it is not a take all or nothing.

And as already said, I think tutorial should move to the repos so that they can be linked to in the api website and copied and compiled for easier onboarding.


> 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.
> 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
> Regards,

Envoyé de mon appareil Android avec Courriel K-9 Mail. Veuillez excuser ma brièveté.