{"id":172,"date":"2016-07-16T16:26:50","date_gmt":"2016-07-16T15:26:50","guid":{"rendered":"https:\/\/blogs.churlaud.com\/somefoobar\/?p=172"},"modified":"2016-07-16T16:46:59","modified_gmt":"2016-07-16T15:46:59","slug":"the-kapidox-poll-results-at-last","status":"publish","type":"post","link":"https:\/\/blogs.churlaud.com\/somefoobar\/2016\/07\/16\/the-kapidox-poll-results-at-last\/","title":{"rendered":"The KApiDox poll results (at last!)"},"content":{"rendered":"

Hey!<\/p>\n

I add to put on the side most of my contributions for some times, as I’m finishing my master thesis in end August, and that I still have some exams in parallel. However it’s important that I give you a feedback about what you expect KApiDox to be. I already apologies, this post is long, but hopefully worth it.<\/p>\n

As some of you might remember, there was a survey about the future of KApiDox<\/a> and more generally of api.kde.org<\/a>. First: thank you for answering, it was very helpful. In this post I’ll review your answers<\/strong> and discuss<\/strong> some of them. Feel free to comment<\/strong> if you do not agree with my understanding or to share your point of view. This is important for the promotion of KDE products.<\/p>\n

Who are you<\/h2>\n

I’m quite happy because I got quite a lot of answers, mostly by KDE developers. Most people seem to be using api.kde.org<\/a> for the KDE Frameworks documentation. An interesting contribution was from a developer that uses only the Qt Frameworks because he founds the KF5 online documentation difficult to use. Well, let’s try to change that!<\/strong><\/p>\n

Current status<\/h2>\n

I worked at modernizing the old api.kde.org<\/a> website. It’s unfortunately not finished. Most of you find the new design nicer<\/strong>, which really pleases me, but still a lot of you think it’s not good enough to attract new people<\/strong>. As next questions show, there is a usability problem to solve<\/strong>: too many clicks to access to one info, more crosslinks are needed… (@VDG: Help!)<\/p>\n

People expect the design to be more responsible for mobile browsing. I must say that I have no knowledge about this. As usual, contribution welcomed<\/strong>: just contact me!<\/p>\n

Some people refered as well to the search box which<\/p>\n

    \n
  1. Redirect to a page with the old design<\/li>\n
  2. Shows results for all libraries, with not very transparent names (Frameworks in module Frameworks5)<\/li>\n<\/ol>\n

    This will change. See next section.<\/p>\n

    The future<\/h2>\n

    Searching<\/h3>\n

    I’d like to let KApiDox generating the search box. This would have the benefit to isolate the results. If you search within the KF5 module, you don’t want to get all the KDELibs, Krita, KDevelop results. Only KF5. And that makes sense.<\/p>\n

    Versioning<\/h3>\n

    About the API versions to show, most of you proposed generating only the major versions plus master<\/strong> (For example when Okular 5 will be released: okular4, okular5, master). This makes sense to me and so I’ll see how to do this.<\/p>\n

    Man\/Qch files<\/h3>\n

    Some people asked me about this. It still exists<\/strong> but hidden: https:\/\/api.kde.org\/qch<\/a>. Currently one script generates them and put them where to be found by links statically written on a hand-written page. I want KApiDox to handle this<\/strong>. It will first generate the full qch\/man file by product (one for all KF5). I’ll think later how to make it smooth library by library if really needed.<\/p>\n

    Products organization<\/h3>\n

    Some of you think only the Frameworks should appear here. Here is why I disagree: we don’t have the man power to maintain scripts generating the [Plasma applets, Okular, Marble, Amarok, KIPI, Krita,…] API documentation. Having a centralized place<\/strong> allow people using more easily<\/strong> what we propose. It only needs to be correctly done (and I hope it will).<\/p>\n

    Now come the question about how to organize things. There is no clear cut<\/strong> whether Plasma and Frameworks API must be on top, or considered only as one other KDE products. It is not my choice to promote one or another library: for now it will stay alphabetical<\/strong>. A problem with the idea of organizing in categories, is that it is difficult to understand this organization. Is Okular in Office or Graphic? I use it only to read PDF and epub, but you can also read pictures… Hum…<\/p>\n

    The inside<\/h3>\n

    It might be less important for you, but I redesigned most of the code (written in Python). Currently everything is done through dictionaries, without too much exception handling. This makes KApiDox not robust at all. I really want to change that, and to ease in the same time the feature extension. Moreover it is part of the Frameworks, but cannot be used in the current state by people out of KDE. I really want to make that nicer, more robust, and more Pythonic. We’ll see \ud83d\ude1b<\/p>\n

    About the expected documentation<\/h2>\n

    This poll raised some comments about the documentation in itself (content) and what could be improved. It doesn’t concern KApiDox but all of us, to provide more useful documentation<\/strong>.<\/p>\n