docs: Add 'Execution of BuildStream Elements' page

[shymega-ct]

WIP!

[abderrahim]

I left a few comments. This document needs a rewrite as it has a lot of factual inaccuracies and wrong terminology.

[abderrahim]

This "hidden" step needs to be "unhidden" in the documentation.

[shymega-ct]

What do you mean, specifically by this? Is there a specific page you could link to for context?

[abderrahim]

I think it makes sense to link to the rest of the documentation, having a document like this feels very weird.

[shymega-ct]

Any page in particular?

[juergbi]

I think this document contains useful information, however, the scope doesn't seem completely clear to me.

Looking at the current BuildStream documentation, I think we're indeed missing a good overview of the different stages for a given element during bst build, so it would be nice to have that.

However, this document includes a lot of details that I don't consider useful as part of an overview. We should link to other sections of the documentation for that (and expand other sections for details that aren't documented anywhere else right now).

I.e., I would define the scope of this page to be an overview of the build process of an element, as I think that's what we're missing most. Or did you have a different scope or target audience in mind? I'm open to other possibilities but I think we should be reasonably clear about what does and what does not belong on this new page.

[shymega-ct]

@juergbi I agree broadly with your thoughts here. I am rewriting this based on your comment, to make it a MVP first, and then iterate upon it.

Would it be best to open a new PR, or keep this one?

[juergbi]

Would it be best to open a new PR, or keep this one?

As this PR already has review comments, at least some of which may remain relevant, I'd probably keep this PR. Depending on how you approach this, a new PR could also be fine but please make sure to address or copy all existing review comments unless they don't apply at all anymore.