Gendoc
Gendoc project is a proposed open source project under the Eclipse Modeling Project.
This proposal is in the Project Proposal Phase (as defined in the Eclipse Development Process) and is written to declare its intent and scope. We solicit additional participation and input from the Eclipse community. Please send all feedback to the Eclipse Proposals Forum.
Background
Model-driven engineering and Model-based development technologies are more and more used but documentation is still necessary as it is generally part of the contract agreement. The idea is to keep only one repository—the model—and to generate document from it.
The main issue of writing documentation linked to a model and diagrams is the synchronization between the document content and the model content, that can be solved by generation from models. The other issue is the style of the generated document, that must often fit exactly an industrial template.
Gendoc has been developed in order to offer an Open Source solution to both problems by generating a document from a document template written directly in the target format (OpenXML or OpenDocument), using EMF models as datasources : the generated document keeps both style and model content synchronization.
Scope
Gendoc generates documentation for EMF models using document templates in formats such as OpenOffice Writer (.odt) or Microsoft Word (.docx).
Generated documents display data extracted from the model with features such as:
- styled text
- images and diagrams
- tables
- bookmarks and hyperlinks
The framework can be extended to add custom generation facilities.
Description
Gendoc extracts data from EMF models and generates documents that fully respect the appearance of your document template.
The generation can be performed in a few steps:
Get or write a standard template document in OpenOffice Writer (.odt) or Microsoft Word (.docx) format, | |
Add script sections to get dynamic content from models : each dynamic section of the template contains a script written in M2T Acceleo language, | |
Reference the model as datasource, | |
Launch the generation directly from the template | |
The generation result fully respects the template document, with all dynamic sections filled with model content |
Styles defined in the template are kept after generation, both on static and dynamic parts.
Gendoc is currently used in several contexts (avionics, space, public services) to produce various kinds of documentation:
- Specification or design document from UML or SysML models
- Requirement document from Req-IF models
- Test plan from a model containing Test scenarii
- Interface configuration document
- Data structure description from specific EMF models
Why Eclipse?
This project is based on top of Eclipse-based technologies : EMF and M2T technologies (compatible with M2T Acceleo for now), and it is already compatible with Eclipse MDT Papyrus through a dedicated extension.
Relationship with other Eclipse Projects
Gendoc has links with EMF and Acceleo as they are key technologies used to define queries and extract data from models. We can also mention links with GMF so that we can generate images from GMF editors. And links with Papyrus so that we can generate images from Papyrus diagrams or extract documentation from UML comments.
Initial Contribution
TOPCASED is offering Gendoc as initial code base. See http://topcased-gendoc.gforge.enseeiht.fr/.
Third party libraries :
- JTidy (MIT license : http://jtidy.sourceforge.net/license.html)
Legal Issues
All contributions will be distributed under the Eclipse Public License.
Committers
The following individual is proposed as leader of the project:
- Anne HAUGOMMARD, Atos
- She is commiter on several TOPCASED components and is the main contributor for Gendoc.
The following individuals are proposed as initial committers to the project:
- Tristan FAURE, Atos
- He is an Eclipse committer on MDT Papyrus project and more generally on TOPCASED components where he has made significant contributions over the last years.
- Anne HAUGOMMARD, Atos
- She is commiter on several TOPCASED components and is the main contributor for Gendoc.
- Aicha BOUDJELAL, Atos
- She works on TOPCASED components and has provided significant contributions to the existing code base of Gendoc.
- Mathieu VELTEN, Atos
- He is an Eclipse committer on MDT Papyrus and works on TOPCASED.
We welcome additional committers and contributions.
Mentors
The following Architecture Council members will mentor this project:
- Cédric Brun (Obeo)
- Jonas Helming
Interested Parties
The following individuals, organisations, companies and projects have expressed interest in this project:
Project Scheduling
- October 2013: code submission and IP review
- November 2013: first builds on the Eclipse infrastructure.
Changes to this Document
Date | Change |
---|---|
20-August-2013 | Document created |
30-September-2013 | Update description section |
11-November-2013 | Second mentor added |