xtext-docs-gen

A simple overview documentation generation for Xtext grammars.

This code was originally forked from https://github.com/darvasd/xtext-docs-gen. That version only works on grammars. If that's all you want, consider using it. Since significant changes are planned, I felt a fork would be appropriate.

Xtext documentation generation

Example

To get the gist of it, have a look at the example below, illustrating the documentation generation.

To check a more comprehensive example, see the documentation generated for the Domainmodel example grammar, using this workflow file.

Usage

1. Add com.epistimis.xtextdocs.xtext as depencency to the MANIFEST.MF of your plug-in project containing the Xtext grammar.

   • You can use the http://epistimis.github.io/xtext-docs-gen/release/ update site to fetch it.

2. Add the documentation generation to your workflow description (.mwe2 file next to your grammar), as a fragment for your language configuration (XtextGeneratorLanguage instance). For example:

    language = StandardLanguage {
    [...]
    	// xtext-docs-gen
    	fragment = DocsGeneratorFragment auto-inject {
    		outputFileName = "docs.md"
    		formatter = MarkdownDocsFormatter {
    			includeSimplifiedGrammar = true
    			mainTitle = "Title text" // optional
    		}
    	}
    [...]
    }
   

   You will need some imports:

   import com.epistimis.xtextdocs.xtext.fragment.DocsGeneratorFragment
   import com.epistimis.xtextdocs.xtext.formatter.MarkdownDocsFormatter
   

3. If you execute your workflow, the grammar documentation should be generated. You can see it in the log as well:

   ...
   5214 [main] INFO  text.fragment.DocsGeneratorFragment  - Generating grammar documentation
   5242 [main] INFO  text.fragment.DocsGeneratorFragment  - Grammar documentation using 'MarkdownDocsFormatter' written to 'docs.md' 
   ...
   

Xcore metamodel documentation generation

Example

To get the gist of it, have a look at the example below, illustrating the documentation generation.

To check a more comprehensive example, see the documentation generated for the Library example metamodel, using this workflow file.

Usage

1. Add com.epistimis.xtextdocs.xcore as depencency to the MANIFEST.MF of your plug-in project containing the Xcore metamodel(s).

   • You can use the http://darvasd.github.io/xtext-docs-gen/release/ update site to fetch it.

2. You may need in addition the following dependencies (you can make them optional if they are only required for the documentation generation): org.eclipse.core.runtime, org.eclipse.emf.ecore, org.eclipse.emf.ecore.xcore.lib, org.eclipse.emf.mwe2.launch, org.eclipse.emf.mwe2.lib, org.eclipse.emf.ecore.xcore, org.eclipse.emf.codegen.ecore, org.apache.commons.logging.

3. Create an MWE2 workflow description (.mwe2 file) that will generate the Xcore documentation. Take this as an example for the Xcore metamodel loading. For the documentation generation configuration, here is an example:

    language = StandardLanguage {
    [...]
    	component = DocsGeneratorFragment {
    		uri = "model/Library.xcore"
    		outputFileName = "LibraryXcore.md"
    		formatter = MarkdownXcoreDocsFormatter {
    			mainTitle = "Library.xcore metamodel description"
    			gitbookLinkStyle = true
    			titleLevelOffset = "0" // optional
    			showOriginalXcoreCode = true  // optional
    			includeToc = true // optional
    		}
    	}
    [...]
    }
   

   You will need some imports:

   import com.epistimis.xtextdocs.xcore.fragment.DocsGeneratorFragment
   import com.epistimis.xtextdocs.xcore.formatter.MarkdownXcoreDocsFormatter
   

4. If you execute your workflow, the grammar documentation should be generated. You can see it in the log as well:

   ...
   3383 [main] INFO  core.fragment.DocsGeneratorFragment  - Xcore documentation using 'MarkdownXcoreDocsFormatter' written to 'LibraryXcore.md.' 
   ...
   

Download

Use https://darvasd.github.io/xtext-docs-gen/release/ as update site and install the Xtext documentation generator or the Xcore documentation generator plug-in.

License

Copyright (c) 2018, 2019 Daniel Darvas Copyright (c) 2024 Epistimis LLC

This program and the accompanying materials are made available under the terms of the Eclipse Public License 2.0 which is available at https://www.eclipse.org/legal/epl-2.0/ .

The Domainmodel grammar is a commented version of the one available in the Xtext documentation, located at https://www.eclipse.org/Xtext/documentation/102_domainmodelwalkthrough.html. See its GitHub page for the list of contributors. Used for demonstration purposes only.

The Library metamodel is an extended version of the one available in the Xcore documentation, located at https://wiki.eclipse.org/Xcore. See this page for the list of contributors. Used for demonstration purposes only.