[PATCH 0/1] Generate application configuration option documentation

[Chris Johns]

Hi Sebastian,

Thank you for this patch. I am sorry but I would like to see this central repo
issue resolved before any generated files are added to any of the project's repos.

I understand to some level the path you are taking and moving along but these
generated files are coming from a personal repo that has changes, processes and
tools that are not being reviewed. I think it would be wise for us to agree on
what is behind all this before we agree to what is being generated.

On 7/7/20 9:25 pm, Sebastian Huber wrote:
> This patch adds the application configuration option documentation generated
> from specification items:
> 
> https://git.rtems.org/sebh/rtems-qual.git/tree/spec/if/acfg

<gulp> That is a lot of files. I am not sure I am ready to accept documentation
as a lot of small files. I am happy to be persuaded otherwise.

It is not clear to me if these YAML files generate documentation, headers, are
requirements or something else. There is nothing I can see in them that defines
their `role` or `roles`. If they do generate files how does that happen and how
are those generated header files related to the C code they are an interface
for? How do I keep each piece in sync? A compile error seems a long way from one
of these YAML files.

For example, if I was to add a YAML file to this directory I have no idea where
I look to find the naming, what roles are assumed, how it integrates into the
existing documentation, doxygen or header files? I also have no idea how I would
create a new API header file? What if I push a new header file to the rtems.git
repo with a new #include in rtems.h. Does a regenerate over write it?

It seems to me the key is the central repo and how it functions, how easy or
hard it is to learn about it and how well it will work in practice. A key
concern is taking it from a single person repo, ie you, to a project wide repo
with concurrent updates ad lots of moving pieces. It is easy to ask these
questions and I appreciate they are not all easy to answer but I think we need
to try.

> The header file is generated by the following script and module:
> 
> https://git.rtems.org/sebh/rtems-qual.git/tree/spec2doc.py
> 
> https://git.rtems.org/sebh/rtems-qual.git/tree/rtemsqual/applconfig.py
> 
> The module uses currently a hack to resolve references external to specification
> items, e.g. sections in the RTEMS Classic API Guide or URLs.  I think we need
> specialized specification items for these external references.

I do not understand what this means?

> Sebastian Huber (1):
>   Document application configuration options
> 
>  cpukit/doxygen/appl-config.h | 4133 ++++++++++++++++++++++++++++++++++
>  1 file changed, 4133 insertions(+)
>  create mode 100644 cpukit/doxygen/appl-config.h

Is this information found in the user manual as well? I am struggling to
understand the relationships and what is being presented where.

Chris