Re: KDE Developer Documentation
Salut Olivier, Having the tutorial next to the code and that they break the compilation if they are out of date is an excellent idea. There is already something similar in Rust[1] were the example in the api documentation are compiled and executed as test. This make it quite easy to write examples that work. From my understanding, rustdoc work like this: 1. The library is build 2. The code example are extracted 3. Each code example is built separately, linked to the library and then ran as a unit test For the case of our libraries: 1. is simple and we are already doing it in the ci :) 2. We would need to either extract the code our self from the code or the generated Doxygen documentation or maybe there is already a way in Doxygen to do it directly 3. I suppose we are already doing it when running autotests But I'm not sure how difficult such a tool willl be to create. There are probably important details that I missed ;) Maybe it is also worth investigation if another open source project has already created such a tool for C++ and Doxygen documentation, and we can't just use their solution. Regards, Carl [1]: https://doc.rust-lang.org/book/ch14-02-publishing-to-crates-io.html#making-useful-documentation-comments Le mardi, décembre 24, 2019 1:19 PM, Olivier Churlaud a écrit : > Hi all (and especially Juan Carlos), > > I just read your report and it's very interesting. I agree with most of what > you wrote. > > I have some minor precisions to give about Techbase: > > The goal was to remove (or only archive) the tutorials on techbase and > replace them by examples within the framework. If having tutorials on a wiki > is nice and findable, it is obsolete very soon after being written and we > lack the resources for keeping an eye on every KDE library to curate and > update the tutorial. > > The conclusion of that was that tutorials need to live next to the frameworks > they belong to AND that they break the compilation if they are out of date. I > did some examples [1] and [2].It's a lot of work to do that, though, but at > least it stays up to date. It could be loaded in api.kde.org in the future > with snippets. That is basically what you propose, issue is that it was never > finished. Pruning Techbase would really help as well. Porting the KDE4 > Tutorials to KF5 in the wiki doesn't seem to me like the best idea because > it's just moving the problem to the future. > > Except of this small remark, I really think you did an awesome job of > synthesis that will be valuable for priorizing the work ahead. > > Best regards > Olivier > > [1] https://phabricator.kde.org/D14955 > [2] https://phabricator.kde.org/D14957 > > Le lundi 23 décembre 2019, 12:00:43 CET Juan Carlos Torres a écrit : > > > Greetings KDE developers and community members! > > In March this year, we started on a journey to take stock of our developer > > documentation and what needs to be done to make them not only more helpful > > to current contributors but also more inviting to new ones as well as > > external users of frameworks. > > The formal work ended in June and I submitted a full report [1] that > > included an analysis of the current state of developer documentation as > > well as the proposed actions the community could take together in the > > months and years ahead. Unfortunately, due to personal and family > > circumstances, I was unable to follow the matter up and for that, I am > > truly sorry. > > Six months have passed since then and while the initial report still holds > > true, events and situations have opened new opportunities for the community > > to focus on. An updated report [2] was submitted to the e.V. reflecting > > these small but important changes. Here is a brief summary of the points in > > the reports. > > > > 1. With Qt 6 and KDE Frameworks 6 underway, it is both all the more > > important and also a perfect opportunity to update our API documentation > > and make sure that they are complete and in good quality. > > > > 2. There is a growing interest in mobile devices and convergent experiences > > which is a good chance to attract more developers into Kirigami and > > Plasma > > Mobile. Updating the developer documentation and documentation systems > > for > > these two projects will be important. > > > > 3. While still important in order to maintain an orderly environment, > > cleaning up and organizing the wikis now takes a lower priority. That > > said, > > certain aspects like guides for new contributors and external developers > > are just as or even more important now than ever. > > > > 4. Since many parts of the developer documentation, particularly those > > related to Frameworks, might be in a period of transition or rapid > > change, > > it might be more practical to focus on creating content first in a > > temporary staging ground before having writers deal with different > >
Re: KDE Developer Documentation
Hi all (and especially Juan Carlos), I just read your report and it's very interesting. I agree with most of what you wrote. I have some minor precisions to give about Techbase: The goal was to remove (or only archive) the tutorials on techbase and replace them by examples within the framework. If having tutorials on a wiki is nice and findable, it is obsolete very soon after being written and we lack the resources for keeping an eye on every KDE library to curate and update the tutorial. The conclusion of that was that tutorials need to live next to the frameworks they belong to AND that they break the compilation if they are out of date. I did some examples [1] and [2].It's a lot of work to do that, though, but at least it stays up to date. It could be loaded in api.kde.org in the future with snippets. That is basically what you propose, issue is that it was never finished. Pruning Techbase would really help as well. Porting the KDE4 Tutorials to KF5 in the wiki doesn't seem to me like the best idea because it's just moving the problem to the future. Except of this small remark, I really think you did an awesome job of synthesis that will be valuable for priorizing the work ahead. Best regards Olivier [1] https://phabricator.kde.org/D14955 [2] https://phabricator.kde.org/D14957 Le lundi 23 décembre 2019, 12:00:43 CET Juan Carlos Torres a écrit : > Greetings KDE developers and community members! > > In March this year, we started on a journey to take stock of our developer > documentation and what needs to be done to make them not only more helpful > to current contributors but also more inviting to new ones as well as > external users of frameworks. > > The formal work ended in June and I submitted a full report [1] that > included an analysis of the current state of developer documentation as > well as the proposed actions the community could take together in the > months and years ahead. Unfortunately, due to personal and family > circumstances, I was unable to follow the matter up and for that, I am > truly sorry. > > Six months have passed since then and while the initial report still holds > true, events and situations have opened new opportunities for the community > to focus on. An updated report [2] was submitted to the e.V. reflecting > these small but important changes. Here is a brief summary of the points in > the reports. > > 1. With Qt 6 and KDE Frameworks 6 underway, it is both all the more > important and also a perfect opportunity to update our API documentation > and make sure that they are complete and in good quality. > > 2. There is a growing interest in mobile devices and convergent experiences > which is a good chance to attract more developers into Kirigami and Plasma > Mobile. Updating the developer documentation and documentation systems for > these two projects will be important. > > 3. While still important in order to maintain an orderly environment, > cleaning up and organizing the wikis now takes a lower priority. That said, > certain aspects like guides for new contributors and external developers > are just as or even more important now than ever. > > 4. Since many parts of the developer documentation, particularly those > related to Frameworks, might be in a period of transition or rapid change, > it might be more practical to focus on creating content first in a > temporary staging ground before having writers deal with different systems > and software. The Wikis are perhaps suited for this kind of workflow. > > These are just some of the high-level points from the two reports and those > documents contain more precise suggestions for the next actions to take. > Again, I apologize to the community for dropping the ball for so long and I > am very excited to get it rolling again. Let's make KDE and its developer > documentation rock even more! > > Attached files: > > 1. 01 KDE Developer Documentation Update Project Report.pdf > 2. 02 KDE Developer Documentation Report Update - 2019-12-09.pdf > >
Re: [KPhotoAlbum] New website design
Nice, nice!! - https://www.kphotoalbum.org/download.html -> Gettin involved link seems to be broken/ish (points to a dir structure, subfolder shows the actual content). Also, someone (or I :) should try to build KPA from scratch at some point and confirm if these instructions are still up-to-date: https://community.kde.org/KPhotoAlbum/build_instructions Anyway, well done everyone, thanks for all your contribution for KPA again this year :) Risto On Sat, Dec 21, 2019 at 5:09 PM Johannes Zarl-Zierl wrote: > Hi everyone! > > The KDE website team has created a new website for KPhotoAlbum. Visually, > the > site reflects our goal of moving closer towards the rest of the KDE > community. > > The old site has served us well over the years, but some things were hard > to > find and other information was duplicated between the website the KDE > Userbase > Wiki. We tried hard to clean up the site content and make it nicer to > browse. > > From a technical viewpoint, the new site uses a static site generator, > which > hopefully makes things easier for the sysadmin team. > > Since the new site has gone live today, I invite everyone to take a look at > > https://kphotoalbum.org > > > A very special thanks to Simon Krull who did the initial port from PHP to > Jekyll, and to Carl Schwan who listened to our needs and polished the site > to > the point where it is today. Without them, this move would not have been > possible! > > While we're at it: another thanks to the KDE sysadmin team! Most of the > time, > it's easy to forget about you because things "just work". Yet, whenever > some > thing breaks or a change requires your help, you're always quick to help! > > > Cheers, > Johannes > (KPhotoAlbum maintainer) > ___ > KPhotoAlbum mailing list > kphotoal...@mail.kdab.com > https://mail.kdab.com/mailman/listinfo/kphotoalbum > -- | risto h. kurppa | risto at kurppa dot fi | http://risto.kurppa.fi
