Skip to content

Small utility for generating LaTeX documentation from Eclipse Modeling Framework metamodels (Ecore files).

Notifications You must be signed in to change notification settings

IncQueryLabs/ecoreDocGen

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Ecore to HTML/LaTeX documentation generator

This is a small utility for generating HTML or LaTeX documentation from Eclipse Modeling Framework metamodels (Ecore files).

The generator uses the structure of the metamodel and the values of the GenModelDoc annotation for creating content.

The generated text will include a section for the main package in the metamodel and subsections for the classifiers, datatypes and enumerations.

Installation

Drag to your running Eclipse workspace.

Available from the Eclipse Marketplace or P2 update site

Usage

Once you installed the two plugins into your Eclipse (or started a runtime Eclipse with them included), just right-click on any .ecore file in your workspace and select "Generate Latex Documentation" or "Generate HTML Documentation" from the menu. As a result a .tex or .html file will be created in the same folder.

To add documentation to your metamodel, you can either use the Ecore Diagram Editor and input the textual descriptions into the "GenModel Doc" field that can be found on the Properties view, or simply add an EAnnotation to any element with the source attribute set to http://www.eclipse.org/emf/2002/GenModel and add a details entry with the key set to documentation and the value containing your description.

Alternatively, you can activate the "Ecore Documentation" view, and enter content directly through that (to use it, first select an Ecore element in the editor, and then click into the view).

We also provide validators based on EMF-IncQuery (http://eclipse.org/incquery) that provide auto-refresh validator for missing/zero-length documentation fields, gradually guiding you to complete documentation nirvana :) See the annotated screenshot below for details.

EcoreDocGen screenshot

For the xtext runtime editor additions bind the following classes in your UIModule:

  • MyEObjectDocumentationProvider.class -> documentation from EMF model/xtext comments
  • MyEObjectHover.class -> hovers for keywords
  • MyProposalProvider.class -> content assist for keywords

Xtext extensions

This tool can be used on Xtext langues too (.xtext files). A documentation of the xtext language with links and tooltips is generated before the metamodel documentation.

In the runtime editor documentations from the metamodel appear in keyword hovers and content assists. Javadoc-like comments are parsed as documentation and are shown for reference hovers and content assists.

Additional syntax

For the HTML Case

The generator supports documentation formatted in Markdown syntax. You can use any Markdown element you like.

For the LaTex Case

The generator supports a subset of Markdown syntax:

  • building lists
  • emphasis of text elements (bold/italic/underline)
  • hyperlinks to remote URLs

Output

HTML

The output format is customizable via CSS. The style-sheet is assumed to be in the same directory as the generated HTML file, and is assumed to be called style.css. An example CSS file can be found in the resources folder of the repository.

LaTex

At least the following packages need to be imported in your LaTex document for the documentation to be valid:

\usepackage{color}
\usepackage{hyperref}
\usepackage{tabularx}
\usepackage{float}

Structure

The following is a short description of the structure used in documenting the metamodels.

EPackage

The documentation section of each metamodel begins with a short introduction explaining the rationale behind the given metamodel and lists the main concepts that are identified and represented by the elements in the metamodel. This introduction is stored in the main EPackage that contains the elements of the metamodel. Finally, the namespace prefix and URI used when persisting instance models of the metamodel are listed.

Elements

After the metamodel introduction, each element in the Package has a subsection which starts with the description of the element, followed by various element properties and tables depending on the type of the element.

EClass

There are two properties and three tables that can appear for an EClass element. The Abstract property specifies that instance models cannot contain EObjects that are instances of this EClass, instead subtypes should be used. The Interface property specifies that no implementation is generated for the EClass. Finally, the list of Supertypes is given.

The tables list the (i) attributes, (ii) references and (iii) operations of the EClass, if there are any. Each table has three columns, the first contains the name of the element (colored blue if derived), the second a list of properties and the third any documentation that is given. Apart from clarifications and rationale, this documentation part can also include validation rules that should be satisfied by instance models (with violations appearing as either errors or warnings).

Some properties are common to the tables, these are the Type (T) and the Cardinality of the element and whether the values are Unordered or Not unique (the default values Ordered and Unique are not shown). In the case of operations, the type and cardinality refers to the return value.

The properties specific to features (attributes and references) are Non-change-able (cannot be modified directly), Volatile (value not stored in a field), Transient (value not persisted), Unsettable (has Unset value) and Derived (value is computed), again, only non-default values are listed.

The property specific to attributes is Identifier, which is true if the value of the attribute identifies the EObject.

The reference-specific properties are Opposite (Op) (the name of the reference in the target that will refer back to the source), Containment (true, if target EObject of this reference is persisted inside source) and Container (Containment is true for opposite of reference). Finally, the property specific to operations is Parameters (any number of parameters with type and cardinality).

EEnum

There is only one table that appears additionally to the element description. The table lists the literals of the EEnum and contains three columns, the name, value and documentation of the literal.

Copyright

All code in this repository is available under the Eclipse Public License v1.0: http://www.eclipse.org/legal/epl-v10.html

About

Small utility for generating LaTeX documentation from Eclipse Modeling Framework metamodels (Ecore files).

Topics

Resources

Stars

Watchers

Forks

Packages

No packages published