Should build products be documented and how?

[Lunaphied]

This is essentially an open invitation for comment on the issue of build products. Below I've laid out some points to potentially address and think about.

1. Where is the best place for products to be documented? Currently it seems like every vendor platform except QuickLogic does this in it's docstring for the platform. This is already rendered in the vendor section of the rendered documentation pages and this is likely a useful place for it to exist in some form. The question is if this adhoc method of documenting the available output products is really ideal given the importance of the information.
2. Should there be a programmatic way to query the available output products? This is likely not particularly necessary, while initially I thought this might be desirable in enabling users to copy all products from a remote machine or into a specific location, this can likely be done just as well or better by just allowing the folder itself to be copied in some form.
3. Should there be any standardized interface to the products? Obviously each platform's output is fairly unique, but there are some similarities, of these I think the most common likely products to exist are "bitstream/input to programmer software" type files, log files from the build, and any potential timing/DRC reports. It might be nice to have these extracted out so that at least some level of generic interface can be built on top. This also might result in a fragile mess that's not worth maintaining.
4. Should we document any changes to the products that a Platform will produce? I think we should, but we should think about how we want to handle this given that vendor toolchains especially can change the outputs they can provide or their format essentially at a whim.

I think I've covered most of my thoughts here. Perhaps in a bit too much detail, but hopefully it gets us thinking about the options we can have.

[Lunaphied]

Just so we lay our thoughts out on these issues also:

1. We think the current format of documenting them in the docstring is reasonable enough, but we might want to think about ways to format it a bit nicer or separate it out on the rendered documentation.
2. Probably not. I can't honestly see anything particularly good coming of this and it results in a list that must be kept in sync with the docstring above and the scripts that generate output, enabling a point of failure for little gain.
3. In general I think this isn't a terrible idea, but I think it would be something where we got to see an actual usecase before thinking about adding. It's likely to not be useful to the vast majority of users and of limited benefit for those that can use it.
4. As I said above, I think it's clear that we should mention if products change, add, remove, rename or change format in some obvious way unless it becomes a problem to keep up.

[whitequark]

It seems like there's nothing actionable here.