Update Atsam BSP Support

[Sebastian Huber]

On 15/12/16 01:24, Chris Johns wrote:
> On 15/12/2016 00:54, Sebastian Huber wrote:
>> I would like to refresh this topic.
>>
>> On 05/10/16 16:17, Gedare Bloom wrote:
>>> That makes sense.
>>>
>>> On Wed, Oct 5, 2016 at 1:17 AM, Sebastian Huber
>>> <sebastian.huber at embedded-brains.de>  wrote:
>>>> >One way to keep this in sync would be to simply write the README of
>>>> each BSP
>>>> >in a certain format, e.g. trac wiki and then simply include the
>>>> content from
>>>> >Git in trac. For example via a modified variant of
>>>> >
>>>> >https://trac.edgewall.org/attachment/wiki/MacroBazaar/Include.3.py
>>>> >
>>>> >
>>>> >Something like this in trac:
>>>> >
>>>> >[[RTEMSGitInclude(c/src/lib/libbsp/arm/atsam/README)]]
>>>> >
>>
>> Would it be possible to add such a Trac add-on? I guess I can modify it
>> so that it works for our purpose, but I don't know how to install it.
>
> Lets see if this is the way we should go before we head down this 
> path. Any support added needs to be secure and this simple issue 
> complicates what we can or should use in Trac.

Yes.

>
>>
>> It would be quite nice if we can write BSP README files in
>> reStructuredText placed in the Git repository that show up on the wiki.
>>
>
> I support using the ReST format.
>
> I am not convinced the Wiki is the best place to land this 
> documentation. These READMEs are really good documentation and we need 
> better BSP documentation. Having it included in the release 
> documentation would be nice.

We already have BSP documentation on the wiki. We have also BSP 
documentation in the README files. What we really need is to document 
things only once for a specific domain and present it to the user where 
it expects the information.

Using README files in ReST format gives us the opportunity to present 
the same information

* in the source tree as a simple text file,
* in the wiki via plug-in, and
* in a user manual via sphinx.

>
> Why not add this documentation to the rtems-docs.git repo?

Why not move the documentation back into the rtems.git repo?

I think is it very nice if you have the BSP sources and a basic 
documentation in the same directory.

>
> Having the BSP doco in the rtems-docs.git repo means we can make and 
> publish the doc formats we support, ie HTML and PDF, because that repo 
> has all the support needed to build the documentation. It is also 
> supported as part of the release procedure.
>
> If the desire is to keep this documentation close to the source, which 
> is attractive, and using rtems-docs.git is a good idea then we need to 
> figure out how to handle this.

I still think that it was not good to move the documentation sources 
into a separate repository. We have a lot of copy and paste in the 
documentation and duplicated information in the header files and the 
documentation files. One option to simplify this would be a XML file 
which defines and documents the RTEMS interfaces (data types, functions, 
defines, macros, etc.) and then use a generator to produce header (maybe 
even with Doxygen comments) files, documentation files and also test cases.

-- 
Sebastian Huber, embedded brains GmbH

Address : Dornierstr. 4, D-82178 Puchheim, Germany
Phone   : +49 89 189 47 41-16
Fax     : +49 89 189 47 41-09
E-Mail  : sebastian.huber at embedded-brains.de
PGP     : Public key available on request.

Diese Nachricht ist keine geschäftliche Mitteilung im Sinne des EHUG.