ecoredoc.md

Ecore Documentation Generation

Nasdanika Ecore Documentation Generator plug-in allows to generate static HTML and Eclipse help documentation for Ecore models. The generator treats documentation annotations content as markdown.

An example of HTML model documentation can be found here.

To generate documentation you will need to create a specification file with a predefined name ecore-docgen.yml. The structure of the file is outlined below:

models:
  - relative path to model 1
  - relative path to model 2
  
apidocs:
  - url of apidoc site 1
  - url of apidoc site 2
  
modeldocs:
  site:
    EPackage NS URI1: documentation location 1
    EPackage NS URI2: documentation location 2  
  help:
    EPackage NS URI1: documentation location 1
    EPackage NS URI2: documentation location 2
      
output:
  site: absolute workspace path to a folder where a static site documentation shall be generated
  help: absolute workspace path to a folder where toc.xml and help content shall be generated
  
toc:
  label: TOC label
  link_to: Where to link
  
set-derived: true             

• models - a list of relative paths to models to generate documentation for - .ecore or .genmodel. All referenced models will also be included. When generator models (.genmodel) are used the generated documentation includes Java type information.
• apidocs - a list of URL's of JavaDoc sites to resolve JavaDoc links. Optional.
• modeldocs - a map of EPackage NS URI's to locations of documentation. Documentation for packages listed under modeldocs is not generated but referenced. When referencing documentation generated by this generator add {{encoded-epackage-ns-uri}} token to the documentation location, e.g. http://mydocsite/mymodeldocs/{{encoded-epackage-ns-uri}}/. The trailing slash is optional.
  • site - model documentation references for the site content.
  • help - model documentation references for the help content. Use relative paths, like ../../../<bundle id>/<model documentation path>/{{encoded-epackage-ns-uri}}/ assuming that documentation is generated to a folder which is an immediate child of containing project, e.g. help. Add more ../ if documentation is generated to nested folders, e.g. doc/model.
• output - outputs to generate
  • site - static HTML site. Optional.
  • help - Eclipse Help. Optional.
• toc - relevant only for Eclipse help generation. Contains toc element attributes such as label or link_to.
• set-derived - set to true in order to set derived attribute on the generated resources.

Example:

models:
  - ../CodegenExamples/model/Sample.ecore
  
output:
  site: /CodegenExamples/site   
  help: /CodegenExamples/help     

toc:
  label: Nasdanika
  link_to: "../org.nasdanika.help/toc.xml#Nasdanika"  

To generate documentation right-click on the specification file and select "Generate Ecore documentation" menu item.

For Eclipse help register the generated toc.xml with the help system.

Please note that the generated site documentation uses AJAX and therefore cannot be served over file:// protocol.

Requirements

The generator uses PlantUML to generate package and class context diagrams. Therefore it requires GraphViz.

Roadmap

• PlantUML plug-in.
• Other extensions.