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 <[email protected]> on behalf of Tuukka
Turunen via Development <[email protected]>
Sent: Friday, February 3, 2023 4:07 PM
To: Shawn Rutledge <[email protected]>; Qt Development
<[email protected]>
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 <[email protected]> on behalf of Shawn
Rutledge via Development <[email protected]>
Date: Friday, 3. February 2023 at 15.56
To: Qt Development <[email protected]>
Subject: Re: [Development] New Qt example development guideline and revamping
examples
On 3 Feb 2023, at 13:56, Tuukka Turunen via Development
<[email protected]> 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).
--
Development mailing list
[email protected]
https://lists.qt-project.org/listinfo/development
