Proposal: Add BSP documentation to BSP build specification

[Sebastian Huber]

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.

Technically, you could use

.. include:

directives, but I would not do this.

-- 

embedded brains GmbH
Sebastian HUBER
Dornierstr. 4
82178 Puchheim
Germany
email: sebastian.huber at embedded-brains.de
Phone: +49-89-18 94 741 - 16
Fax:   +49-89-18 94 741 - 08
PGP: Public key available on request.

embedded brains GmbH
Registergericht: Amtsgericht München
Registernummer: HRB 157899
Vertretungsberechtigte Geschäftsführer: Peter Rasmussen, Thomas Dörfler
Unsere Datenschutzerklärung finden Sie hier: https://embedded-brains.de/datenschutzerklaerung/