Improve docc documentation

Sources/Adwaita/Adwaita.docc/Advanced/CreatingWidgets.md

@@ -0,0 +1,63 @@
+# Creating widgets
+
+Widgets are special views that do not provide a collection of other views as a content,
+but have functions that are called when creating or updating the view.
+Normally, a widget manages a GTK or Libadwaita widget using the C API.
+
+## Recreate the Text widget
+In this tutorial, we will recreate the ``Text`` widget.
+A widget conforms to the ``Widget`` protocol:
+```swift
+struct CustomText: Widget { }
+```
+You can add properties to the widget:
+```swift
+struct CustomText: Widget {
+
+    var text: String
+
+}
+```
+This widget can be called in a view body using `CustomText(text: "Hello, world!")`.
+Now, add the two functions required by the protocol:
+```swift
+import CAdw
+
+struct CustomText: Widget {
+
+    var text: String
+
+    public func container(modifiers: [(View) -> View]) -> ViewStorage { }
+    public func update(_ storage: ViewStorage, modifiers: [(View) -> View], updateProperties: Bool) { }
+
+}
+```
+Import CAdw which exposes the whole C Libadwaita and Gtk API to Swift.
+
+## The `container(modifiers:)` function
+This function initializes the widget when the widget appears for the first time.
+It expects a ``ViewStorage`` as the return type.
+In our case, this function is very simple:
+```swift
+func container(modifiers: [(View) -> View]) -> ViewStorage {
+    .init(gtk_label_new(text)?.opaque())
+}
+```
+
+## The `update(_:modifiers:updateProperties:)` function
+Whenever a state of the app changes, the ``Widget/update(_:modifiers:updateProperties:)`` function of the widget gets called.
+You get the view storage that you have previously initialized as a parameter.
+Update the storage to reflect the current state of the widget:
+```swift
+func update(_ storage: ViewStorage, modifiers: [(View) -> View], updateProperties: Bool) {
+    if updateProperties {
+        gtk_label_set_label(storage.pointer, text)
+    }
+}
+```
+
+## Containers
+Some widgets act as containers that accept other widgets as children.
+In that case, use the ``ViewStorage``'s `content` property for storing their view storages.
+In the ``Widget/update(_:modifiers:updateProperties:)`` function, update the children's storages.
+Take a look at the code of the container widgets in this library as a reference.

Sources/Adwaita/Adwaita.docc/Advanced/PublishingApps.md

@@ -0,0 +1,48 @@
+# Publishing apps
+
+Learn how to publish your apps using Flatpak.
+
+Once you feel ready to publish your app to [Flathub](https://flathub.org/), or
+to a [self-hosted repository](https://docs.flatpak.org/en/latest/hosting-a-repository.html),
+you can follow this step-by-step guide.
+
+## Create a Flatpak manifest
+You have to create a Flatpak manifest, similar to the one [here](https://github.com/flathub/io.github.david_swift.Flashcards/blob/master/io.github.david_swift.Flashcards.json).
+Find detailed information in the [Flatpak documentation](https://docs.flatpak.org/en/latest/manifests.html).
+This is the only code that should be submitted to Flathub.
+There will be a new repository created under `flathub/app-id` that hosts the manifest.
+
+### SDK Extension for Swift 5
+I recommend using the SDK Extension for building the app.
+Add the following snippet.
+
+```json
+"sdk-extensions": [
+  "org.freedesktop.Sdk.Extension.swift5"
+]
+```
+
+### Generate sources for the Swift Package Manager
+You cannot access the web while building the app.
+Therefore, you need to add all the dependencies as modules to the manifest file.
+This can be automated using the [Flatpak builder tool for SPM](https://github.com/flatpak/flatpak-builder-tools/tree/master/spm).
+
+## MetaInfo file
+In the Flatpak Manifest file, under the build commands, you should add the [code to install the app's
+MetaInfo file](https://github.com/flathub/io.github.david_swift.Flashcards/blob/c5c0421ffb5589641ddb44a269a6e7e07d430581/io.github.david_swift.Flashcards.json#L49).
+The MetaInfo file is located in the app's main repository (not in the Flathub repository).
+Take a look at the example [here](https://github.com/david-swift/Memorize/blob/main/data/io.github.david_swift.Flashcards.metainfo.xml).
+
+## Desktop entry file
+[This line](https://github.com/flathub/io.github.david_swift.Flashcards/blob/c5c0421ffb5589641ddb44a269a6e7e07d430581/io.github.david_swift.Flashcards.json#L50) in the example installs the Desktop Entry file.
+It is located in the [main repository](https://github.com/david-swift/Memorize/blob/main/data/io.github.david_swift.Flashcards.desktop).
+
+## Check the requirements
+Before submitting an app to Flathub, make sure to check the [requirements](https://docs.flathub.org/docs/for-app-authors/requirements),
+[MetaInfo guidelines](https://docs.flathub.org/docs/for-app-authors/metainfo-guidelines/), and [quality guidelines](https://docs.flathub.org/docs/for-app-authors/metainfo-guidelines/quality-guidelines).
+Then, test and submit the app following the [submission instructions](https://docs.flathub.org/docs/for-app-authors/submission).
+
+## Get the badges
+Use the [Flathub badges](https://flathub.org/badges) to inform users about the simple installation option.
+Even more assets are available [here](https://github.com/flathub-infra/assets).
+

Sources/Adwaita/Adwaita.docc/Adwaita.md

@@ -81,3 +81,14 @@ Find more information in the [template repository](https://github.com/AparokshaU
 ### Tutorials
 
 - <doc:Table-of-Contents>
+
+### Basics
+
+- <doc:CreatingViews>
+- <doc:Windows>
+- <doc:KeyboardShortcuts>
+
+### Advanced
+
+- <doc:CreatingWidgets>
+- <doc:PublishingApps>

Sources/Adwaita/Adwaita.docc/Basics/CreatingViews.md

@@ -30,7 +30,7 @@ In this example, the widgets ``HeaderBar`` and ``Text`` are used.
 `padding` is a view modifier, a function that modifies a view, which adds some padding around the text.
 
 ## Create custom views
-While directly adding widgets into the `Window`'s body might work for very simple apps,
+While directly adding widgets into the ``Window``'s body might work for very simple apps,
 it can get messy very quickly.
 Create custom views by declaring types that conform to the ``View`` protocol:
 ```swift

Sources/Adwaita/Adwaita.docc/Basics/Windows.md

@@ -32,7 +32,7 @@ struct HelloWorld: App {
 ```
 
 ## Showing windows
-Every app contains the property `app`. 
+Every app contains the property ``App/app``. 
 You can use this property for running functions that affect the whole app, e.g. quitting the app.
 Another use case is showing a window:
 ```swift
@@ -66,7 +66,7 @@ It should be used for opening windows that cannot be presented more than once
 and for moving a window that is already open into the foreground.
 
 ## Adding windows
-You can call the `addWindow(_:parent:)` function instead of `showWindow(_:)`
+You can call the ``GTUIApp/addWindow(_:parent:)`` function instead of ``GTUIApp/showWindow(_:)``
 if you want to add and focus another instance of a window type:
 ```swift
 @main