docs: how bluebuild works

[xynydev]

https://blue-build.org/learn/how/

Outline the process of turning recipes into containerfiles, the repo structure, how the modules are launched and what they do, etc.

Will need help from @gmpinder here at least. You got a good docs streak going with the #48 PR lol, so creating an issue for this now.

[xynydev]

I figured that an example recipe would be a great way to start this, so here's a sketch. The comments are WIP and won't stay like that. Also, the indentation is fucked up. But at this exists now.

# example-recipe.yml

# metadata
name: turquoise
description: An example recipe for explaining how BlueBuild works.

# base image
base-image: ghcr.io/ublue-os/silverblue-main
image-version: latest

# stages, to explain all that
stages:
  - name: helix
    from: docker.io/library/rust
    modules:
      - type: script
        snippets:
          - apt-get update && apt-get install -y git # Install git
          - git clone https://github.com/helix-editor/helix.git # Clone the helix repo
          - cd helix && RUSTFLAGS="-C target-feature=-crt-static" cargo install --path helix-term # Use cargo to install
          - mkdir -p /out/ && mv $CARGO_HOME/bin/hx /out/hx && mv runtime /out/ # Move bin and runtime

modules:
  # helix stage copy
  - type: copy
    from: helix
    src: /out/hx
    dest: /usr/bin/
  - type: copy
    from: helix
    src: /out/runtime
    dest: /usr/lib64/helix/
	
  - type: files
    files:
       - usr: /usr # need to do the files-related changes because i don't wanna be stuck explaining this

  # classic module of the build-time-only variety
  - type: rpm-ostree
    repos:
       - https://copr.fedorainfracloud.org/coprs/atim/starship/repo/fedora-%OS_VERSION%/atim-starship-fedora-%OS_VERSION%.repo
     install:
        - fish
        - starship

  # classic module of the post-boot variety
  - type: default-flatpaks
    user:
        install:
            - org.kde.krita
            - org.blender.Blender
            - org.gnome.World.PikaBackup

[xynydev]

I was just imagining what an explainer for the build system could look like and I feel like Animotion slides (reveal.js under the hood) could be a great fit. If I can make like a system for it that that shows text on the bottom and such. Joy of Code uses it for their pleasing coding tutorial videos and I'm just hearing the whole doc pages read in their voice, lol.

Just a thought. Feels like it would be easier to explain the whole thing in more of a slides format.

[xynydev]

I got Animotion working locally as an embed on a doc page. It works pretty well and I could see this thing explained with it.

However, it also has to work in the context of a documentation webpage. What we gain in interactivity we lose in responsiveness, and the slideshows are basically unusable on mobile.

It will likely be better to just write the docs normally. If any extra interactivity is desired it is possible to add that in with some code.

[gmpinder]

What parts of the tool do we want to explain and how deep should we go? Are you thinking just high level this is how it orchestrates building? Do we want to go into detail about making use of cache for building?

I personally don't mind having animations, so long as I'm not the one making them lol.

[xynydev]

I personally don't mind having animations, so long as I'm not the one making them lol.

Ha. It might be something I use to motivate myself, or it might a distraction. We'll see.

What parts of the tool do we want to explain and how deep should we go? Are you thinking just high level this is how it orchestrates building? Do we want to go into detail about making use of cache for building?

It's a bit nebulous in my head. I guess the goal for me would be to have casual docs users able to understand how their image is built from a recipe, with the most important part being generating the RUN statement for modules. Another goal is helping potential contributors understand the system more, making it easier to delve into code or writing docs or whatever.

It would be great to be able to write all about the caching and the 'drivers' you are working on and such, maybe as some sort of collapsible sections or sub-articles. But that's mostly your area of expertise nowadays, and I wouldn't consider it as important the higher-level overview. I don't know how much you're interested in writing technical documentation, maybe some devlog-style writing would be interesting too. I plan on doing a big technical write-up once/if Workshop gets to a stage where a novice could just click-click through it and customize their own image.

[gmpinder]

I have a branch called create-docs on the CLI repo which I'm trying to use a MD book site that would be useful for making documentation specifically for bluebuild cli.

I haven't made any real progress on it. I do want to try to pick that back up though, because it would be really useful to keep the docs for the CLI in the same repo. I could reserve these docs mostly for the more technical side of the CLI and then we can have the website handle all the more higher-level user-facing features.

[xynydev]

@gmpinder if you see a way to integrate those docs into the main website somehow, it wouldn't be hard to write a plugin for Starlight / Astro that fetches the MD from the CLI repo.