Structure the documentation wiki

[cecilebraun]

From #198

What needs to be done:

• Design a rudimentary table of contents (TOC) for the documentation. (estimate: 0.5 hours)
• Follow the Style Requirements of org.eclipse.mylyn.wikitext to implement the TOC on a wiki (either the toolchain wiki, but I think s dedicated wiki would make even more sense). (estimate: 4-8 hours)
• Create a Plug-In that generates documentation in Eclipse Help and PDF from the Wiki (you can use the ProR Docu Plugin as an example) (estimate: Depending on experience, 4-16 hours)
• Automate the building of Eclipse Help Plugin and PDF on Jenkins (estimate: Depending on experience, 2-16 hours)

Total effort: 10.5 hours - 6 days, depending on experience

Who is doing it:

• Initially, @idelatorre had been assigned
• @MERCEmentre has been filling in, while @idelatorre was unavailable
• @idelatorre will be active again starting 27-Jan-2014, assining additional SQS resources.

[jastram]

Mathilde Arnaud will help with these activities.

[agracia]

We have developed a plugin that generates documentation in Eclipse Help from the Eclipse Wiki succesfully (https://wiki.eclipse.org/OpenETCS_toolchain), and we expect to have the generation of pdfs soon.

We are also working with jenkins, once we have the environment correclty configured I think the creation of the jobs and the launching of the building of the plugin will not take much time.

[jastram]

Hello @agracia, thanks for starting this. I have two comments:

• Is there a reason you created the pages at eclipse.org? I would consider a gitHub wiki more appropriate.
• Is it possible to work with subpages, rather than sections? I anticipate a lot of content.

Thanks!

[agracia]

Hello again @jastram

• We have had some problems with the generation of documentation from the github wiki during the development of the plugin that are not in the Eclipse wiki. Because of that, we have decided to prepare a first runnable version of the plugin for the Eclipse wiki as a first approach. In this way, a first version of the plugin is available and operative while we try to solve the problems and prepare the final version for the github wiki.
• We can have as many pages as we need in the wiki. The plugin creates the whole structure of htmls (one html for each wiki page) and a directory for the images. This structure is shown in the Eclipse Help and the user can navigate through these pages easily using the tree of contents and the corresponding forward and back arrows.

On the other hand, we are testing the plugin with an installation of jenkins we have in a virtual machine. We are synchronizing the connection to a github repository where the plugin is and launching the building. However, the configuration of this job depends on the Jenkins we are using, so we expect to prepare a step-by-step document with the details of the configuration so in the future the job can be prepared in the Jenkins tool to be used.

Regards

[cecilebraun]

Hello @agracia
Thanks for the contribution.
Is it possible to provide information on how to add some text to be taken into account by your plug-in ?
Like for example how to add this https://github.com/openETCS/toolchain/wiki/Data-Dictionary-Plugin to the documentation ?

[cecilebraun]

At Scrum telco 25.02 proposed a structure https://github.com/openETCS/toolchain/wiki/Doucmentation-Structure-Proposal to be continued