Routes for hosting ECore documentation of session registered packages in the NFS web application

[pvlasov]

Overview

In NFS ECore models are the center of knowledge accumulation. A system may be composed of multiple evolving models produced by different teams. Hosting up-to-date model documentation in the web application itself shall facilitate better understanding of the domain for all parties involved in the application development. In the released software this feature can be either disabled or make available to certain groups of users.

Design

• Create route(s) which will generate HTML documentation from ECore metadata and documentation annotations.
• Provide support of markdown in documentation annotation with pegdown.
• Use PegDownProcessor(int options) constructor and pass Extensions TABLES | WIKILINKS options to turn on support of tables and wiki links.
• Use [markdownToHtml(String,LinkRenderer)](http://www.decodified.com/pegdown/api/org/pegdown/PegDownProcessor.html#markdownToHtml%28java.lang.String, org.pegdown.LinkRenderer%29) method to generate HTML from markdown in order to support the following link formats:
  • [[ecore>classifier@namespace_uri|text]], with the pipe and the text after it being optional, defaulting to the classifier name. E.g. [[ecore>EString@http://www.eclipse.org/emf/2002/Ecore]] or [[ecore>EString@http://www.eclipse.org/emf/2002/Ecore|String]].
  • [[bundle>bundle_symbolic_name/bundle_resource|text]] - link to a resource in a bundle.
  • Optionally provide support for referencing an image in a bundle, e.g. [[!bundle>...]].
  • .md resources shall be transparently translated to HTML.
  • Provide extension points similar to Eclipse Help TOC to allow bundles to contribute entries to the documentation table of contents, in addition to the entries in the CDO session package registry.
  • Use ExtensionTracker to track documentation extensions - see code samples.
  • Provide an extension point for EAnnotation renderers matching by source. E.g. ECORE documentation renderer would treat details key as markdown, while form annotations renderer would create a table with form controls configuration.

This approach will allow to create cross-links between the model and custom documentation. For example, user stories and designs can be written in the terms of the model's "ubiquitous language".

NOTE

Model generators shall be configured not to suppress GenModel annotations so the documentation annotations are available at runtime: