updating the example to use core22, the latest version of the kde-neon extension, and the latest version of KCalc that supports Qt 5;
some restructuring, as well as adding a new section to the guide (see below); and
generally updating the language/style used etc.
In issue #3 I suggested that I might also take a look at the related page for the kde-neon extension. I was able to do so, but as it's a standalone document (and as this PR is big enough as-is) I'll raise a separate PR for it.
Files:
The main file is qt-applications.md. The four other files (all in the github directory) are the two versions of snapcraft.yaml referred to in the guide, together with a shell script and simple README file. I tentatively assumed that these documents could be transferred to a new snapcraft-docs/kcalc-example repo on GitHub, in line with what has been done elsewhere (e.g. snapcraft-docs/moon-buggy for the C/C++ guide) but if an alternative location is better please let me know as I'm happy to revise the relevant files. (For what it's worth, I chose kcalc-example to avoid any possible confusion whatsoever with the existing/official KCalc snap published by KDE.)
Explanation/Comments:
Thanks to the great documentation on snapcraft.io, I found that it was quite quick and easy to build a working KCalc snap, even though I hadn't built any snaps before.
That said, I encountered a couple of small-ish challenges and I thought it would be worth documenting how I overcame them. These related to:
(a) KCalc using the wrong cursor theme and size on GNOME/Wayland; and
(b) the lack of error sounds
I thought that it would be best to split the guide into 'building a basic working snap' and 'refining the snap' rather than presenting one long snapcraft.yaml file from the outset - my hope was that this would demonstrate just how easy it is to build a working proof of concept snap, and that issues are often quite easy to overcome in a fairly modular way by using build parts.
However I think there's a good case for splitting the improvements out into a separate guide. Not only would this shorten the how-to, but it could cover other areas that I haven't addressed, like D-Bus integration and adopting the system theme (aside from the cursors, the current snap just uses Qt 5's default Fusion theme). What do you think? I'm more than happy to split the guide into two now, or revisit this on.
In relation to style, I used 'you' and 'we' as a way of distinguishing between 'generic steps that a reader should take when creating a Qt/KDE Frameworks snap' and 'specific steps that we took for the purposes of our KCalc example' respectively. Hopefully this comes across okay, but if it's too clunky/confusing/annoying let me know and I'll revise it.
The diff looks worse than it really is - the bulk of the additions relate to the new 'improvements' section, and I made some other structural changes like swapping the apps and parts sections around because it flowed better (e.g. introducing the kde-neon extension earlier than in the original).
Thinking about other (longer term?) improvements to the Qt/KDE Frameworks snap documentation:
I assume that we'll need an equivalent how-to for Qt 6 and KDE Frameworks 6 based applications now that the kde-neon-6 extension has been merged into Snapcraft - is this being handled internally?
It might also be useful to have a platform 'landing' page, which could provide users with:
a quick overview to Qt-based snaps
a short section on 'why package Qt 5 applications as snaps'
links to the how-to guides, extension pages and any other to-be-written Qt-specific documentation (e.g. regarding theming or Qt for Python).
I'm more than happy to volunteer for either/both, if there's any interest in them.
I have level 1 trust on the Snapcraft Discourse, so I should be able to upload the finalised version once complete.
Summary: This pull request features an updated version of the Qt 5 and KDE Frameworks applications how-to guide available at https://snapcraft.io/docs/qt5-kde-applications.
The changes made include:
core22, the latest version of thekde-neonextension, and the latest version of KCalc that supports Qt 5;In issue #3 I suggested that I might also take a look at the related page for the kde-neon extension. I was able to do so, but as it's a standalone document (and as this PR is big enough as-is) I'll raise a separate PR for it.
Files: The main file is qt-applications.md. The four other files (all in the
githubdirectory) are the two versions of snapcraft.yaml referred to in the guide, together with a shell script and simple README file. I tentatively assumed that these documents could be transferred to a newsnapcraft-docs/kcalc-examplerepo on GitHub, in line with what has been done elsewhere (e.g.snapcraft-docs/moon-buggyfor the C/C++ guide) but if an alternative location is better please let me know as I'm happy to revise the relevant files. (For what it's worth, I chosekcalc-exampleto avoid any possible confusion whatsoever with the existing/official KCalc snap published by KDE.)Explanation/Comments: Thanks to the great documentation on snapcraft.io, I found that it was quite quick and easy to build a working KCalc snap, even though I hadn't built any snaps before.
That said, I encountered a couple of small-ish challenges and I thought it would be worth documenting how I overcame them. These related to: (a) KCalc using the wrong cursor theme and size on GNOME/Wayland; and (b) the lack of error sounds
I thought that it would be best to split the guide into 'building a basic working snap' and 'refining the snap' rather than presenting one long snapcraft.yaml file from the outset - my hope was that this would demonstrate just how easy it is to build a working proof of concept snap, and that issues are often quite easy to overcome in a fairly modular way by using build parts.
However I think there's a good case for splitting the improvements out into a separate guide. Not only would this shorten the how-to, but it could cover other areas that I haven't addressed, like D-Bus integration and adopting the system theme (aside from the cursors, the current snap just uses Qt 5's default Fusion theme). What do you think? I'm more than happy to split the guide into two now, or revisit this on.
In relation to style, I used 'you' and 'we' as a way of distinguishing between 'generic steps that a reader should take when creating a Qt/KDE Frameworks snap' and 'specific steps that we took for the purposes of our KCalc example' respectively. Hopefully this comes across okay, but if it's too clunky/confusing/annoying let me know and I'll revise it.
The diff looks worse than it really is - the bulk of the additions relate to the new 'improvements' section, and I made some other structural changes like swapping the
appsandpartssections around because it flowed better (e.g. introducing thekde-neonextension earlier than in the original).Thinking about other (longer term?) improvements to the Qt/KDE Frameworks snap documentation:
kde-neon-6extension has been merged into Snapcraft - is this being handled internally?I'm more than happy to volunteer for either/both, if there's any interest in them.
I have level 1 trust on the Snapcraft Discourse, so I should be able to upload the finalised version once complete.