GSOC 2017 Approaching

[Chris Johns]

On 11/01/2017 22:11, Tanu Hari Dixit wrote:
>     There was a gsoc project a few years ago which read the user
>     documentation for confdefs.h and
>     used that to generate the menu, options, tool tips, data type, etc.
>     Ignoring issues Chris and I
>     have discussed about how using the documentation to do this risks
>     having the doc and tool
>     out of sync with the real code, there is a basic new issue:
>
>     + the documentation is in a new format - Sphinx - so even if we used
>     the exact same
>     approach, the tool reads the wrong format input.
>
>     That project is discussed at
>     https://devel.rtems.org/wiki/Projects/GSoC/ApplicationConfigurationGUI
>     <https://devel.rtems.org/wiki/Projects/GSoC/ApplicationConfigurationGUI>
>     and includes links to the github.
>
>     Seeing if we can solve the code=doc=tool problem and updating the
>     tool so the Sphinx docs
>     match the tool options would be a good project and make this concept
>     something we could
>     trust.
>
> I suppose, one would have to make a parser for the Sphinx documentation
> as already made for the tex files.

I do not agree with this approach. The documentation is in ReST format 
and that is not easy to parse at the level a tool like Sphinx does. I 
also feel limiting the ReST format so we can parse it, or tagging or 
adding other delimiters raises complexity increasing the fragility of 
the whole process.

>     Off the top of my head, I think Chris and I thought that if the
>     confdefs.h documentation
>     could be generated from that file AND the tool also read that file,
>     then it would be OK.
>     The risk is getting them out of sync.
>
>
> I don't understand why would the sync between doc=tool be a problem when
> the tool parses from the doc. Kindly help me with this.

The documentation is in a one repo and the code and tools are in 
different repos so you need to ensure all the pieces line up or version 
skew between different parts could be hard to debug. It also creates a 
dependence issue between different parts that needs to be resolved to 
create a release.

After thinking about this some more I am starting to wonder if a C 
header file driving the whole process is upside down. I am starting to 
wonder if a controlled format such as XML could be used to define the 
run-time configuration of RTEMS and we generate an init.c or system.h or 
what ever users currently have. How a user defines the application 
configuration is something I have not thought much about other than the 
typical approaches such as INI or XML. A format like XML opens up the 
ability to formally check the configuration making it attractive.

> Also, in another thread the devs discussed about incorporating third
> party packages. I am interested in porting mathematical packages (as
> listed in the open projects page: mtrxmath, ccmath, openGL Mathematics
> and others. I will be glad to port them and write tests and examples
> once ported (like a simple/sanity test as Joel mentioned in the thread).
> However, I am unsure if this project will be enough to fill in three
> months worth of work; also, whether this is in general interest of the
> community.

Tests and examples for 3rd party packages is something we are to figure 
out however I feel this would need to be defined by the core developers 
before being a real project.

I recently discussed with Joel a project to create simple examples for 
all the directives in RTEMS so we have working code we can cut and paste 
into each directive's documentation. The idea is the code is for users 
so not the same as tests which can be difficult to read when wanting to 
see how to use a call. I think the coding complexity is medium, however 
getting all this to build and run on a wide number of targets plus the 
number of examples to be created makes it a challenging project. I 
suspect there will be some design/architecture issues to be resolved to 
make the examples simple yet working.

Chris