Add "Guides" section to owlkettle docs

[PhilippMDoerner]

As we chatted about earlier, the nimibook docs should include a Guides section.

The intent should be to provide guides for various ways of using owlkettle. This shall be subdivided into further subsections if that ever grows.

The guides should be included for now:

• centralize state across your application by defining ref-types that you pass around

In that case, consider adding links to the owlkettle-crud example (and maybe pull the owlkettle-CRUD example into the owlkettle repo?).

Future additions may include:

• How to cross-compile to windows
• How to deploy as a flatpak
• How to deploy as an AppImage
• How to deploy for X-Distro (deb, rpm, AUR)
• Suggestions for multithreading

[can-lehmann]

I wrote a bit about application architecture: https://can-lehmann.github.io/owlkettle/book/guides/application_architecture.html

[PhilippMDoerner]

For the multithreading guide I'd want to include the following:

1. Do they have a lot of IO they want to do in parallel or a lot of computation that should happen in another thread?
2. for IO, just use async-IO with GTK's timeout functionality as wrapped by owlkettle
3. for lots of one-off computation, use a channels with GTK's general task procs as wrapped by owlkettle (forgot the name tbh)
4. for setups with long-running threads, use createChannel with a while-loop proc and channels, or contemplate using ThreadButler

I'll eventually get around to this, it's just taking a bit to solidify the multithreading stack. I've learned about sanitizers and a lot more about using grinds and am thus working on making sure that the various channel implementations satisfy those (they do not in some cases). Only once that stands can I finish work on ThreadButler and be able to suggest it.

[ITwrx]

I was wondering why the crud example was not ever added to the docs.

Also, when trying to first learn about writing a GUI program with something like gtk or owlkettle, the basic, general desktop programming info can be a little scarce. At first, I didn't know about doing something in a separate thread so you don't lock up your GUI, for instance. I had seen little references here and there, but didn't understand much. My point is that guides that are more general, like various desktop programming topics (that just happen to use owlkettle), would likely help with long term adoption, so i big 👍 up from me.

[can-lehmann]

I was wondering why the crud example was not ever added to the docs.

It is. See the bottom of https://can-lehmann.github.io/owlkettle/book/guides/application_architecture.html. It is not linked in the main examples page, as it is not an example officially shipped with owlkettle.

[ITwrx]

I think i forgot about that, but that's not as discoverable as being with the rest of the examples. I said "docs", when i should have said "examples". What is the distinction being made with the crud example not being officially shipped with owlkettle? I mean, why isn't it? Is it because of the funding credit?