Gendoc

The project has been approved and is awaiting provisioning.

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 :

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