docs: bake guides and refactor reference

[crazy-max]

follow-up #928 (review)

creates guides for bake as our reference docs for this command is quite huge and I think bake deserves its own section.

bake guides will be then added on docs web site, see docker/docs#14905. Preview: https://deploy-preview-14905--docsdocker.netlify.app/build/bake/file-definition/

I plan to add more concrete examples and use cases. let me now if the structure sounds good to you. cc @tonistiigi @dockertopia

Signed-off-by: CrazyMax crazy-max@users.noreply.github.com

[dockertopia]

LGTM.

[tonistiigi]

If you want, you can merge as-is and follow up on the next PRs.

[tonistiigi]

This doesn't go in the correct order atm. "Configuring builds" starts with an example using variables but variables have not been explained yet.

My suggestion is that "configuring builds" would start with examples about variables and also contains attrs.

Next topic is "User defined HCL functions"

[crazy-max]

We define variables in "File definition" so I think it's fine? But the "HCL variables and functions" doesn't look quite right and should only be about HCL user-defined functions as you said. I made some changes about it.

[tonistiigi]

grouping variables with "configuring" and functions with the rest of the function section makes more sense to me. Yeah, the title should be just HCL functions as there are stdlib functions as well(should we list them?).

[tonistiigi]

This should start with an intro, e.g. "Bake supports loading build definition from files. But sometimes you need even more flexibility to configure this definition. For this use case, you can define variables inside the bake files that can be set by the user with environment variables or by attribute definitions in other bake files. If you wish to change a specific value for a single invocation you can use a --set flag."

[crazy-max]

Added an intro and also moved some bits from HCL user-defined funcs specific to build configuration in this page.

[tonistiigi]

Let's just call it "Building Compose files" and add an extra intro block explaining that you can just build compose files directly and how each service definition inside the compose files maps to a target (could have a simple example for this as well).

[crazy-max]

There is already a basic example in "File definition" for compose files. Also in "Target" specification we already have a note saying "In the case of compose files, each service corresponds to a target.".

This "Extension field with Compose" page is very specific to the case where some fields are not supported in the compose spec.

Do you think we should move the Compose file section to this page so we don't have many things around about compose but on the same page?

[tonistiigi]

I don't think this provides enough context for the new reader. They already need to know that they are looking for x-bake to find this useful. You can leave the example in the file definition but there is much more to explain in here.

[crazy-max]

Added some context for building compose files. In a follow-up we could add new use cases to show how to use compose build fields from the specification and how they are translated to target with bake (secrets, cache).

[tonistiigi]

👍 Let's get this in and iterate from here.