Add the posibility to run `bst doc` to generate the documentation for the bst tree

[BuildStream-Migration-Bot]

See original issue on GitLab In GitLab by [Gitlab user @tcanabrava] on Jul 8, 2020, 11:43

Quite a few of the buildstream projects are meta projects that are supposed to be integrated to other projects, but those projects defines variables that should be set, or specific intrinsics that are not easily discoverable unless you download the meta projet and open the files to understand what's missing.

I'ts important to have a de-facto way to produce documentation for meta-projects.

[BuildStream-Migration-Bot]

In GitLab by [Gitlab user @tristanvb] on Jul 8, 2020, 12:29

Definitely insightful and interesting to consider.

Thus far, BuildStream does not take a particular stance on how projects should interact, but leaves this mostly to the user, I'm not sure that it's appropriate for BuildStream to lay down any laws here (in the same way that a C compiler does not have an opinion on how one project provides header files to it's downstreams).

Certainly there is something to consider along these lines though, and we have some interesting materials:

• Elements can already have "description" fields, what do we use these for ?
• Project options have "description" fields, again unused.

If we did have a sort of convention where a project uses underscore prefixes for elements which are considered private, then we could generate docs using some of these description fields, and more clearly deleniate what elements are part of a projects API surface (and fair game to depend on across a junction).

[BuildStream-Migration-Bot]

In GitLab by [Gitlab user @tristanvb] on Jul 8, 2020, 12:47

marked this issue as related to #1353

[BuildStream-Migration-Bot]

In GitLab by [Gitlab user @cs-shadow] on Jul 8, 2020, 13:06

I would echo Tristan's sentiment that I'm not sure if this functionality needs to exist in BuildStream itself.

For the meantime, some sort of convention-based system is probably the most feasible option. Like having _ prefixes for private elements and such.

If we were to implement such a functionality in BuildStream, we can probably consider having visibility attributes that define which downstream targets can depend on a given element, similar to what bazel does. Hypothetically speaking, if we had that such a visibility attribute, BuildStream could handle that in a generic way without having to know details of a specific project. And then something like bst show --filter visiblity=public could solve your needs. But, this would need a well thought-out proposal first, as it can get hairy around the edges.