Proposal: Add BSP documentation to BSP build specification

[Chris Johns]

On 12/11/20 3:46 am, Gedare Bloom wrote:
> On Wed, Nov 11, 2020 at 9:36 AM Sebastian Huber
> <sebastian.huber at embedded-brains.de> wrote:
>>
>> On 11/11/2020 17:32, Gedare Bloom wrote:
>>
>>> Hi Sebastian,
>>>
>>> What is the advantage of doing this?
>>>
>>> I don't immediately see the rationale.
>>
>> The advantage is that as soon as you add/remove a BSP family or variant
>> to/from the build you can generate an up to date user manual.
>>
>> Having documentation of the BSP in the build specification helps to
>> concentrate things which belong together in one spot. In a next step we
>> should think about adding the BSP option documentation to the user manual.
>>
> OK, consolidation is a reasonable argument, and the possibility to
> 'script' some doc generation from the build spec is intriguing.  It
> continues to raise the bar on documentation patches, but I'm fine with
> it.

Gedare, I agree with your comments. Thanks.

Sebastian, will there be an opportunity to add more detail about the BSP such as
the BSP options that we have struggled to historically document?

One area of concern is the freedom we have with editing in ReST. We are moving
this content from the wiki to ReST and this will move us to YAML fragments.
Would having the ability to include a .rst file from the generated segment
provide a way we can support a controlled format for part of the BSP and then a
more free format in the doc repo?

Chris