[Development] New Qt example development guideline and revamping examples

Topi Reiniö Topi.Reinio at qt.io
Wed Apr 19 18:36:05 CEST 2023


Hi,

Heads up for anyone involved in the work of revamping examples and specifically their documentation:

We've updated the guideline for adding an example to a specific category. Instead of using the \meta {category} {<category>} command directly, please use the newly introduced \examplecategory macro instead. This macro expands to the above \meta command and also adds the example to a category-specific group. This enables automatic listing of examples per category, as in https://doc-snapshots.qt.io/qt6-dev/qtexamplesandtutorials.html#application-examples.

Here's the updated part of the guideline: https://wiki.qt.io/Qt6/Example-Guideline#Categorisation

We've already updated existing occurrences in all qt5 submodules.

Thanks!
\topi

________________________________
From: Development <development-bounces at qt-project.org> on behalf of Tuukka Turunen via Development <development at qt-project.org>
Sent: Friday, February 3, 2023 4:07 PM
To: Shawn Rutledge <Shawn.Rutledge at qt.io>; Qt Development <development at qt-project.org>
Subject: Re: [Development] New Qt example development guideline and revamping examples


”The point of examples is to show how to use Qt to do specific things.  Some of them are redundant? Well there is not only one way to do things; why should we hide something cool just because it’s only the second of several choices? In the future I think we will hesitate to write new examples if the risk of deletion is so high. ”



On the contrary, target is to make the examples more useful by ensuring all examples follow the best practices and improving how they are shown in documentation and creator welcome page. No-one want to delete examples that are good and useful for our users.



The list I sent is examples that are currently not shown in docs or creator, so users are not that likely to find them. We should also think why these examples are not shown? Typically this is not by accident, but it has been determined that it is better to hide the example.



The list contains 113 examples, so I am sure there are some that would be better to fix to meet the example guideline, write the documentation and show the example. But for many of these the value as an example is low. Thus is better to move to manual tests in case we need it for testing purposes.



Yours,



                Tuukka



From: Development <development-bounces at qt-project.org> on behalf of Shawn Rutledge via Development <development at qt-project.org>
Date: Friday, 3. February 2023 at 15.56
To: Qt Development <development at qt-project.org>
Subject: Re: [Development] New Qt example development guideline and revamping examples



On 3 Feb 2023, at 13:56, Tuukka Turunen via Development <development at qt-project.org> wrote:



pdf/pdfviewer



Depends which one you mean.  They are all new and maintained at this point.  There is some redundancy on purpose, because there are multiple PDF-viewing components.  So I wouldn’t delete any of them.



quick/delegatechooser



We need to make sure we are showing DelegateChooser somewhere; it’s quite useful.  I don’t see it in any other examples.



quick/pointerhandlers



I plan to give the pointerhandlers example some proper docs.  It only recently graduated from being a manual test.  It may not look like a “proper desktop application” but that’s not the point.



… many more I don’t remember so well, and then...

wayland/custom-extension

wayland/custom-extension/compositor

wayland/custom-extension/cpp-client

wayland/custom-extension/qml-client

wayland/custom-shell/client-plugin

wayland/custom-shell/compositor

wayland/hwlayer-compositor

wayland/minimal-cpp

wayland/server-buffer

wayland/server-buffer/compositor

wayland/server-buffer/cpp-client

widgets/itemviews/flattreeview

widgets/itemviews/storageview

...




As Kimmo mentioned, we should aim to check and move (or remove if not seen relevant as a manual test by the module maintainer) these during February.



You are talking about removing them from the manifest, not removing the code, I hope? Even so...



The point of examples is to show how to use Qt to do specific things.  Some of them are redundant? Well there is not only one way to do things; why should we hide something cool just because it’s only the second of several choices?



In the future I think we will hesitate to write new examples if the risk of deletion is so high.



Move them to manual tests?  Well that’s better than deleting, but users will not tend to find those, because we don’t ship them.



Snippets? I think those should be complete enough to actually run.  Otherwise it’s too much work to keep re-verifying that they still work.  And it is more useful to users to start with a complete, minimal example that already runs, and then add the extra functionality that they want, rather than just some stanza of code that got broken at some point along the way.  With QML that’s not too hard; so my rule is every QML snippet should be a complete standalone file that can run with the qml tool.  But with C++ snippets it’s not convenient to make them runnable; so when we convert C++ examples to snippets, we can expect them to rot, unless we come up with a way to auto-wrap them with boilerplate and test them automatically on a periodic basis (in CI, in pre-release testing or whatever).


-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.qt-project.org/pipermail/development/attachments/20230419/a1ba47ef/attachment.htm>


More information about the Development mailing list