Document other use cases apart from flatpak
Context
There are two primary audiences for the documentation:
- Freedesktop SDK developers — how to contribute to the project itself (https://gitlab.com/freedesktop-sdk/freedesktop-sdk/-/blob/master/CONTRIBUTING.md)
- Developers from other projects that want to use Freedesktop SDK in those projects — how to use freedesktop-sdk to implement their own projects
For the second, uur current documentation is very flatpak focused (which is normal as it was the born of the project and still our main target) Still, a lot more things can be done with freedesktop-sdk:
- Build OS (bootable) images
- Use a fdsdk as a junction and create image on top; this is what GNOME is doing here: https://gitlab.gnome.org/GNOME/gnome-build-meta/ (https://gitlab.com/freedesktop-sdk/freedesktop-sdk/-/blob/master/BOOTABLE_IMAGES.md?ref_type=heads)
- Examples of project doing this:
- os.gnome.org/
- https://carbon.sh/
- Container / runtimes
- Build a flatpak runtime (As you can see in the README this was the initial use case)(https://gitlab.com/freedesktop-sdk/freedesktop-sdk#usage)
- Examples:
- freedesktop-sdk itself: https://gitlab.com/freedesktop-sdk/freedesktop-sdk/-/blob/master/elements/flatpak-release-repo.bst
- GNOME flatpak runtimes: https://gitlab.gnome.org/GNOME/gnome-build-meta/-/blob/master/elements/flatpak-runtimes.bst
- Examples:
- Build containers / OCI images
- fdsdk as a junction to build you own container images (https://gitlab.com/freedesktop-sdk/infrastructure/freedesktop-sdk-docker-images)
- Use a fdsdk to create a custom tarball with toolchain and other build tools
- Build a snap (pending a fix to add fdsdk to the snap store)
- Build a flatpak runtime (As you can see in the README this was the initial use case)(https://gitlab.com/freedesktop-sdk/freedesktop-sdk#usage)
Relevant documentation links:
- https://gitlab.com/freedesktop-sdk/freedesktop-sdk/-/wikis/Using%20freedesktop-sdk#buildstream-projects
- https://gitlab.com/freedesktop-sdk/freedesktop-sdk/-/wikis/Project%20structure
- Wiki: https://gitlab.com/freedesktop-sdk/freedesktop-sdk/-/wikis/home
Other docs:
- Buildstream docs (build tool used by freedesktop-sdk): https://docs.buildstream.build/2.0/index.html
- flatpak docs: https://docs.flatpak.org/en/latest/available-runtimes.html?highlight=runtimes
Acceptance Criteria
- README is updated
- Webpage is updated
- Documentation should be available in a dedicated documentation portal, with the main Freedesktop SDK site linking to the portal; this should be probably added as merge request in the main website repository (https://gitlab.com/freedesktop-sdk/freedesktop-sdk.gitlab.io/); Idea is to have something similar to https://docs.flatpak.org/en/latest/ , but for freedesktop-sdk
- Move all the current disjointed documentation to that portal, documenting the different use cases as above
- Structure the documentation taking in account the audiences above
Edited by Javier Jardón