Hello Chris,
On 08/06/2021 05:07, Chris Johns wrote:
On 7/6/21 6:40 pm, Christian Mauderer wrote:> I think the Options don't need
documentation changes because the options in the
waf based build system are now documented directly in the yaml files and printed
if you generate the default config.
Hmm I am not sure I agree with the premise the YAML is the documentation. The
user manual exists for this purpose and user wanting to explore RTEMS would look
there rather than cloning the repo, running commands etc.
The alternative would be to duplicate documentation of the BSP options
in the user manual. And (manual) duplication is always a bad idea if you
ask me. Or move the description from the yaml to the documentation
entirely which means that you need to pick the correct version of the
documentation for the sources. It also means that you have to look up
the meaning of each option in the right version of the manual instead of
in the default config.
I think the only reasonable option (with the current structure) would be
to somehow automatically generate that documentation part. For example
by creating the default BSP config.ini for each BSP and adding it to the
user manual. But that has to be an automatic process. Otherwise it will
be out of date right from the beginning.
I accept the current defaults etc work flow is a good place to start for the waf
conversion project but we need to do a lot more to make accessing the YAML
easier. The wscript contains the only rtems.git repo means to read the YAML and
the pickled data and that limits how we can change and evolve this.
We could merge documentation and code again. From my point of view that
would make it simpler to add documentation for new features right when
they are implemented and there would be always the right version for a
source commit. I don't really know the reason why it was split up in
2015 / 2016 so we would have to look that up before discussing further
into that direction. Additionally it would need discussion how and where
(for example) network stacks would be documented.
Best regards
Christian
_______________________________________________
devel mailing list
devel@rtems.org
http://lists.rtems.org/mailman/listinfo/devel
