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.hu...@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.hu...@embedded-brains.de
PGP : Public key available on request.
Diese Nachricht ist keine geschäftliche Mitteilung im Sinne des EHUG.
_______________________________________________
devel mailing list
devel@rtems.org
http://lists.rtems.org/mailman/listinfo/devel
