Proposal: Add BSP documentation to BSP build specification

[Chris Johns]

On 12/11/20 6:13 pm, Sebastian Huber wrote:
> On 11/11/2020 23:16, Chris Johns wrote:
> 
>> 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.
> I currently work only on a plan. This is not a work which I can start immediately.
>>
>> 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?
> 
> Yes, one of the goals of the new build system was to be able to add the BSP
> options to the documentation:
> 
> https://docs.rtems.org/branches/master/eng/build-system.html#goals
> 
> For this it is easier to generate also the documentation sections related to a BSP.
> 
>>
>> 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?
> 
> For the BSPs you would have a list of sections:
> 
> documentation-sections:
> 
> - header: A
> 
>   section: |
> 
>     Some arbitrary ReST text.
> 
> - header: B
> 
>   section: |
> 
>     Some more ReST text. You can also use ${optabc:/name} to references BSP
> options.
> 
> I think this should be enough to document a BSP.

I am not sure. For example ...

https://docs.rtems.org/branches/master/user/bsps/bsps-arm.html#debugging

... has a picture of the wire links needed to enable debugging. We need to be
able to quickly and easily produce this sort of documentation.

We need the more formal part for the options etc and we need this flexibility
including images and more. I am concerned not providing something will result in
the Wiki being used with the issues that brings.

> Technically, you could use
> 
> .. include:
> 
> directives, but I would not do this.

What about something in YAML that generates the include?

Chris