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.hu...@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.hu...@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/
_______________________________________________
devel mailing list
devel@rtems.org
http://lists.rtems.org/mailman/listinfo/devel
