Skip to content

Commit

Permalink
[526521] Documentation updates
Browse files Browse the repository at this point in the history
  • Loading branch information
@ujhelyiz
ujhelyiz committed Nov 30, 2017
1 parent 92db51e commit 41b98d2
Show file tree
Hide file tree
Showing 10 changed files with 88 additions and 153 deletions.
3 changes: 3 additions & 0 deletions documentation/org.eclipse.viatra.documentation.help/.vscode/settings.json
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
{
"java.configuration.updateBuildConfiguration": "disabled"
}
33 changes: 33 additions & 0 deletions documentation/org.eclipse.viatra.documentation.help/.vscode/tasks.json
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
{
// See https://go.microsoft.com/fwlink/?LinkId=733558
// for the documentation about the tasks.json format
"version": "2.0.0",
"tasks": [
{
"taskName": "asciidoc-website",
"type": "shell",
"command": "mvn -B -o generate-resources -Dasciidoc.highligher=highlight.js -Dasciidoc.header=false -Dasciidoc.toc=false",
"group": "build",
"presentation": {
"echo": true,
"reveal": "always",
"focus": false,
"panel": "dedicated"
},
"problemMatcher": []
},
{
"taskName": "asciidoc",
"type": "shell",
"command": "mvn -B -o generate-resources",
"group": "build",
"presentation": {
"echo": true,
"reveal": "always",
"focus": false,
"panel": "dedicated"
},
"problemMatcher": []
}
]
}
142 changes: 6 additions & 136 deletions documentation/org.eclipse.viatra.documentation.help/pom.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,10 @@
</parent>
<artifactId>org.eclipse.viatra.documentation.help</artifactId>
<packaging>eclipse-plugin</packaging>
<properties>
<asciidoc.highligher>coderay</asciidoc.highligher>
<asciidoc.header>true</asciidoc.header>
</properties>
<build>
<plugins>
<plugin>
Expand Down Expand Up @@ -40,148 +44,14 @@
</goals>
<configuration>
<backend>html5</backend>
<sourceHighlighter>coderay</sourceHighlighter>
<sourceHighlighter>${asciidoc.highlighter}</sourceHighlighter>
<preserveDirectories>true</preserveDirectories>
<outputDirectory>html</outputDirectory>
<attributes>
<linkcss>true</linkcss>
<last-update-label>false</last-update-label>
<toc>false</toc>
</attributes>
<!-- <headerFooter>false</headerFooter> -->
</configuration>
</execution>
<execution>
<id>generate-tutorial</id>
<phase>generate-resources</phase>
<goals>
<goal>process-asciidoc</goal>
</goals>
<configuration>
<sourceDocumentName>tutorial.adoc</sourceDocumentName>
<backend>html5</backend>
<sourceHighlighter>highlight.js</sourceHighlighter>
<preserveDirectories>true</preserveDirectories>
<outputDirectory>html</outputDirectory>
<headerFooter>true</headerFooter>
<attributes>
<linkcss>true</linkcss>
<last-update-label>false</last-update-label>
</attributes>
</configuration>
</execution>
<execution>
<id>generate-releases</id>
<phase>generate-resources</phase>
<goals>
<goal>process-asciidoc</goal>
</goals>
<configuration>
<sourceDocumentName>releases.adoc</sourceDocumentName>
<backend>html5</backend>
<sourceHighlighter>highlight.js</sourceHighlighter>
<preserveDirectories>true</preserveDirectories>
<outputDirectory>html</outputDirectory>
<headerFooter>true</headerFooter>
<attributes>
<linkcss>true</linkcss>
<last-update-label>false</last-update-label>
</attributes>
</configuration>
</execution>
<execution>
<id>generate-query-api</id>
<phase>generate-resources</phase>
<goals>
<goal>process-asciidoc</goal>
</goals>
<configuration>
<sourceDocumentName>query-api.adoc</sourceDocumentName>
<backend>html5</backend>
<sourceHighlighter>highlight.js</sourceHighlighter>
<preserveDirectories>true</preserveDirectories>
<outputDirectory>html</outputDirectory>
<headerFooter>true</headerFooter>
<attributes>
<linkcss>true</linkcss>
<last-update-label>false</last-update-label>
</attributes>
</configuration>
</execution>
<execution>
<id>generate-vql</id>
<phase>generate-resources</phase>
<goals>
<goal>process-asciidoc</goal>
</goals>
<configuration>
<sourceDocumentName>query-language.adoc</sourceDocumentName>
<backend>html5</backend>
<sourceHighlighter>highlight.js</sourceHighlighter>
<preserveDirectories>true</preserveDirectories>
<outputDirectory>html</outputDirectory>
<headerFooter>true</headerFooter>
<attributes>
<linkcss>true</linkcss>
<last-update-label>false</last-update-label>
</attributes>
</configuration>
</execution>
<execution>
<id>generate-evm</id>
<phase>generate-resources</phase>
<goals>
<goal>process-asciidoc</goal>
</goals>
<configuration>
<sourceDocumentName>evm.adoc</sourceDocumentName>
<backend>html5</backend>
<sourceHighlighter>highlight.js</sourceHighlighter>
<preserveDirectories>true</preserveDirectories>
<outputDirectory>html</outputDirectory>
<headerFooter>true</headerFooter>
<attributes>
<linkcss>true</linkcss>
<last-update-label>false</last-update-label>
</attributes>
</configuration>
</execution>
<execution>
<id>generate-transformations</id>
<phase>generate-resources</phase>
<goals>
<goal>process-asciidoc</goal>
</goals>
<configuration>
<sourceDocumentName>transformations.adoc</sourceDocumentName>
<backend>html5</backend>
<sourceHighlighter>highlight.js</sourceHighlighter>
<preserveDirectories>true</preserveDirectories>
<outputDirectory>html</outputDirectory>
<headerFooter>true</headerFooter>
<attributes>
<linkcss>true</linkcss>
<last-update-label>false</last-update-label>
</attributes>
</configuration>
</execution>
<execution>
<id>generate-addons</id>
<phase>generate-resources</phase>
<goals>
<goal>process-asciidoc</goal>
</goals>
<configuration>
<sourceDocumentName>addons.adoc</sourceDocumentName>
<backend>html5</backend>
<sourceHighlighter>highlight.js</sourceHighlighter>
<preserveDirectories>true</preserveDirectories>
<outputDirectory>html</outputDirectory>
<headerFooter>true</headerFooter>
<attributes>
<linkcss>true</linkcss>
<last-update-label>false</last-update-label>
</attributes>
<headerFooter>${asciidoc.header}</headerFooter>
</configuration>
</execution>
</executions>
Expand Down
3 changes: 2 additions & 1 deletion ...entation/org.eclipse.viatra.documentation.help/src/main/asciidoc/query-api.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -638,7 +638,7 @@ We already have some connector implementations for the most common use cases. Fo
[[query-api-registry-connectors]]
[source,java]
----
IRegistrySourceConnector connector = new SpecificationMapSourceConnector("my.source.identifier", false /* do not include these in default views */);
IRegistrySourceConnector connector = new SpecificationMapSourceConnector("my.source.identifier", true /* include these in default view; fqn clashes are errors */);
IQuerySpecification<?> specification = /* available from somewhere */
Expand All @@ -651,6 +651,7 @@ connector.addQuerySpecificationProvider(provider);
connector.removeQuerySpecificationProvider(specification.getFullyQualifiedName());
----

NOTE: The default view assumes all queries loaded there have a single qualified name. If this cannot ensured, the source should not be added to the default views and specific views are to be created accordingly.

== Performance tuning and special engine modes

Expand Down
28 changes: 28 additions & 0 deletions documentation/org.eclipse.viatra.documentation.help/src/main/asciidoc/tools.adoc
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
= Query Development Tools in VIATRA
ifdef::env-github,env-browser[:outfilesuffix: .adoc]
:rootdir: .
ifndef::highlightjsdir[:highlightjsdir: {rootdir}/highlight.js]
ifndef::highlightjs-theme[:highlightjs-theme: foundation]

:imagesdir: {rootdir}/images
:toclevels: 2
:toc:
:toc-placement: macro
:numbered:
:icons: font
:sectnums:
:sectnumlevels: 4
:experimental:
:sectlinks:



toc::[]

include::tools/query-tests.adoc[leveloffset=+1]

<<<
include::tools/query-profiling.adoc[leveloffset=+1]

<<<
include::tools/maven.adoc[leveloffset=+1]
13 changes: 7 additions & 6 deletions ...tation/org.eclipse.viatra.documentation.help/src/main/asciidoc/tools/maven.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -62,7 +62,7 @@ To use VIATRA Query features, add the repository and the required dependencies t
</repositories>
----

== viatra-maven-plugin ==
== viatra-maven-plugin

The maven plugin requires information from the used EMF packages and additionally the EMF packages should be able loaded as well. For this reason, it is important to add references to EPackages and Genmodels together with the corresponding dependencies.

Expand All @@ -74,7 +74,7 @@ Since 1.5, it is possible to use the project dependencies without declaring them
* Explicit dependency declarations are transitive, so you don't need to specify all dependencies in all POM.XML files. Note that in some cases you need to add extra dependencies with specific versions (e.g. emf.core) if your genmodel requires a higher version than what is provided by the viatra-maven-plugin. This way you can redefine the EMF versions used by the generator.
* If a pattern file in a Maven project imports patterns from another project on which it depends, make sure that the files containing the imported patterns are included in the dependency's Maven artifact.

.Example POM.XML (based on link:http://git.eclipse.org/c/viatra/org.eclipse.viatra.examples.git/tree/cps/frameworktests/org.eclipse.viatra.gui.tests.queries/pom.xml[CPS example])
.Example POM.XML (based on link:http://git.eclipse.org/c/viatra/org.eclipse.viatra.git/tree/query/tests/org.eclipse.viatra.query.runtime.cps.tests/pom.xml[CPS example])
[source,xml]
----
<pluginRepositories>
Expand Down Expand Up @@ -152,7 +152,7 @@ Since 1.5, it is possible to use the project dependencies without declaring them
</build>
----

=== Troubleshooting ===
=== Troubleshooting

.Cyclic linking
In a project that contains multiple pattern definition files, there is a slight chance you get an error message like follows:
Expand Down Expand Up @@ -193,7 +193,7 @@ pattern myPattern(...) {

You have to rename `util.vql` to `a_util.vql` and `logic.vql` to `b_logic.vql`, so that the former is processed before the latter.

.Ambyguous types
.Ambiguous types

If you get type errors during validation such as `ERROR:foo cannot be resolved.` or `ERROR:Ambiguous variable type defintions: [Foo, Bar], type cannot be selected` although the query files are valid in Eclipse, check the cross-references in your ecore/genmodel files by opening them with a text editor. If their URIs are workspace-based, i.e. they start with `platform:/resource`, you have to map those URIs to absolute `file:` URIs by including URI mappings in the viatra-maven-plugin configuration (since 1.6):

Expand Down Expand Up @@ -224,7 +224,8 @@ If you get the error
`ERROR:Variable foo has a type Foo which has multiple definitions: 'file://C:\project\model/../../anotherProject/model/usedMetamodel.ecore' -- 'file://C:\project\../anotherProject/model/usedMetamodel.ecore'`
make sure that the genmodelUri in the viatra-maven-plugin's configuration is *exactly* the same as the URI in your .genmodel file, e.g. if your `metamodel.ecore` resides in the `model` subfolder, this will be the configuration with the correct relative URI:

<source lang="xml">
[source,xml]
----
<plugin>
<groupId>org.eclipse.viatra</groupId>
<artifactId>viatra-maven-plugin</artifactId>
Expand All @@ -236,6 +237,6 @@ make sure that the genmodelUri in the viatra-maven-plugin's configuration is *ex
</metamodels>
</configuration>
</plugin>
</source>
----

NOTE: The URIs should be the same *after* URI mapping if used.
5 changes: 2 additions & 3 deletions ....eclipse.viatra.documentation.help/src/main/asciidoc/tools/query-profiling.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ ifndef::imagesdir[:imagesdir: {rootdir}/../images]
= Debugging and Profiling Graph Patterns

[[rete-visualizer]]
== Rete Visualizer =
== Rete Visualizer

.Installation
* Install the *Query Visualization* feature group from the VIATRA update site.
Expand All @@ -27,8 +27,7 @@ image:tools/rete_visualizer.png[]
== Local Search Debugger

.Installation

The Local Search Debugger Tooling is available in the Query Visualization feature group.
* The Local Search Debugger Tooling is available in the Query Visualization feature group.

.Usage
* Open the Local Search Debugger view in Eclipse
Expand Down
2 changes: 1 addition & 1 deletion .../org.eclipse.viatra.documentation.help/src/main/asciidoc/tools/query-tests.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -118,7 +118,7 @@ public class CustomIntegerAccess extends JavaObjectAccess{

=== Coverage analysis and reporting ===

Since 1.6 (see {{bug|514628}}), you can add analyzers to a test object which measure various metrics of query execution. For example, you can analyze coverage during testing:
Starting with VIATRA 1.6 (see link:http://bugs.eclipse.org/514628[bug 514628]), you can add analyzers to a test object which measure various metrics of query execution. For example, you can analyze coverage during testing:

[source,xtend]
----
Expand Down
2 changes: 1 addition & 1 deletion ...g.eclipse.viatra.documentation.help/src/main/asciidoc/tutorial/environment.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,6 @@ image::tutorial/install.png[Install window]

For a faster installation, you may deselect the _Contact all update sites during install\..._ field, but then it might be necessary to install the required _Xtext Runtime_ manually.

This document assumes that the CPS metamodels are installed into the Eclipse instance. They are available from the p2 repository https://hudson.eclipse.org/viatra/job/viatra-examples-cps/lastSuccessfulBuild/artifact/cps/releng/org.eclipse.viatra.examples.cps.update/target/repository/
This document assumes that the CPS metamodels are installed into the Eclipse instance. They are available from the p2 repository http://download.eclipse.org/viatra/examples/cps

VIATRA defines a custom perspective called `Transformation Development` that includes a few views and shortcuts that make it easier to develop queries and transformations. The remainder of the tutorial expects that this perspective is selected; in case a different perspective is used, the corresponding views and wizards are still available in their standard respective locations.
10 changes: 5 additions & 5 deletions documentation/org.eclipse.viatra.documentation.help/viatra.toc.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -59,16 +59,16 @@
<topic href="html/evm.html" label="The Event-Driven Virtual Machine">
</topic>
</topic>
<topic label="Development Tools">
<topic href="html/tools.html" label="Development Tools">
<topic href="html/tools/preferences.html" label="Preferences">
</topic>
<topic href="html/tools/query-profiling#rete-visualizer" label="Rete Visualizer">
<topic href="html/tools.html#rete-visualizer" label="Rete Visualizer">
</topic>
<topic href="html/tools/query-profiling#local-search-debugger" label="Local Search Debugger">
<topic href="html/tools.html#local-search-debugger" label="Local Search Debugger">
</topic>
<topic href="html/tools/query-tests.html" label="Functional Testing of Model Queries">
<topic href="html/tools.html#query-tests" label="Functional Testing of Model Queries">
</topic>
<topic href="html/tools/maven.html" label="Using VIATRA Query in Maven Projects">
<topic href="html/tools.html#viatra-maven-plugin" label="Using VIATRA Query in Maven Projects">
</topic>
</topic>
<topic href="html/addons.html" label="Addons and Integrations">
Expand Down

0 comments on commit 41b98d2

Please sign in to comment.