Skip to content

Commit 19139db

Browse files
nkoesternkoester
authored
Merge pull request #58 from modelix/docs/migrate-existing
MODELIX-392: Improve the documentation skeleton
2 parents ee7b33a + 0fbcb53 commit 19139db

19 files changed

+418
-162
lines changed

‎README.md‎

Lines changed: 24 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,16 @@
1+
# The Modelix Project
2+
The modelix project develops an open source platform for (meta-)models on the web. We are native to the web and the cloud.
3+
4+
For general information on modelix, please refer to the [official modelix homepage](https://modelix.org) as well as the [platform documentation](https://docs.modelix.org).
5+
6+
For individual component specific documentation, see https://docs.modelix.org/modelix/latest/reference/components.html
7+
18
# modelix.core
29

3-
All the Modelix components that don't have a dependency on JetBrains MPS
10+
This repository contains the core components of the modelix platform.
11+
All components in this repository have no dependencies to JetBrains MPS.
12+
If you are looking for MPS related modelix components, see https://github.com/modelix/modelix.
13+
414

515
## Development
616

@@ -17,3 +27,16 @@ To enable pre-commit hooks, you have to run the following command initially afte
1727
$ pre-commit install
1828
pre-commit installed at .git/hooks/pre-commit
1929
```
30+
31+
32+
# Authors
33+
34+
Development of modelix is supported by [itemis](https://itemis.com)
35+
36+
37+
# Copyright and License
38+
39+
Copyright © 2021-present by the modelix open source project and the individual contributors. All Rights Reserved.
40+
41+
Use of this software is granted under the terms of the Apache License Version 2.0.
42+
See the [LICENSE](LICENSE) to find the full license text.

‎docs/global/modules/core/pages/howto/usage-light-model-client.adoc‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
= How-To use the `light-model-client
2+
:navtitle: Use the `light-model-client`
3+
4+
5+
NOTE: If you are interested in a more practical usage of what is presented here, check out the https://github.com/modelix/modelix.samples[samples project^]
6+
7+
8+
Creating an instance that loads the entire model from the server can be done like this:
9+
10+
[source,kotlin]
11+
--
12+
val client = LightModelClientJVM.builder()
13+
.url("ws://localhost/json/v2/test-repo/ws") // optional, by default it connects to the MPS plugin
14+
.build()
15+
--
16+
17+
You have to set a *model query* using `changeQuery()` to tell the server in what data you are interested in.
18+
19+
CAUTION: Without a query the client will not receive any data.
20+
21+
[source,kotlin]
22+
--
23+
client.changeQuery(buildModelQuery {
24+
root {
25+
descendants { }
26+
}
27+
})
28+
--
29+
30+
To read or write any nodes you have to start a read/write transaction by using `runRead {}`/`runWrite {}`.
31+
An exception is thrown when you try to access a node outside a transaction.
32+
33+
[source,kotlin]
34+
--
35+
val rootNode = client.waitForRootNode()!!
36+
client.runRead {
37+
val modules = rootNode.getChildren("modules")
38+
// ...
39+
}
40+
--
41+
42+
CAUTION: If you try to access a node that is not included in your *model query* an exception is thrown.
43+
44+
You can use `INode.isLoaded()` to check if a node was loaded on the client to prevent this exception.
45+
You can also filter a list of nodes like this: `node.getChildren("modules").filterLoaded()`, to iterate only over the nodes that are included in your query.
46+

‎docs/global/modules/core/pages/howto/usage-metamodel-generator.adoc‎

Lines changed: 149 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,149 @@
1+
= How-To apply the Meta-Model Generator using the Gradle Plugin
2+
:navtitle: Generate `Kotlin`/ `Typescript` API from MPS language
3+
4+
NOTE: If you are interested in a more practical usage of what is presented here, check out the https://github.com/modelix/modelix.samples[samples project^]
5+
6+
. To apply the xref:core:reference/component-metamodel-generator-gradle.adoc[] to an existing JetBrains MPS language, it is necessary to build the project via Gradle.
7+
+
8+
This How-To assumes a folder structure as follows
9+
+
10+
[source,]
11+
--
12+
.
13+
├── mps
14+
│   ├── build
15+
│   ├── metamodel
16+
│ │   └── [kotlin gradle sub-project]
17+
│ │
18+
│   ├── languages
19+
│ │   └── [your MPS languages]
20+
│   └── solutions
21+
│    └── [your MPS solutions]
22+
│
23+
├── settings.gradle.kts
24+
├── gradle.properties
25+
├── gradle.properties
26+
├── build.gradle.kts
27+
└── [...]
28+
--
29+
30+
. Once you have your Gradle setup done, add the following lines the respective files.
31+
32+
.. `gradle.properties` file:
33+
+
34+
[source,kotlin]
35+
--
36+
modelixCoreVersion=1.4.10
37+
mpsVersion=2021.3.2
38+
39+
[...]
40+
--
41+
+
42+
NOTE: The versions listed here are not the latest versions, refer to the repositories or use our latest release.
43+
//TODO add 'latest release ref'
44+
45+
46+
.. `settings.gradle.kts` file:
47+
+
48+
[source,kotlin]
49+
--
50+
pluginManagement {
51+
val modelixCoreVersion: String by settings
52+
plugins {
53+
// the gradle plugin that provides easy access to the meta-model generator
54+
id("org.modelix.metamodel.gradle") version modelixCoreVersion
55+
56+
[...]
57+
}
58+
repositories {
59+
maven { url = uri("https://artifacts.itemis.cloud/repository/maven-mps/") }
60+
61+
[...]
62+
}
63+
}
64+
65+
[...]
66+
--
67+
68+
.. `build.gradle.kts` file:
69+
+
70+
[source,kotlin]
71+
--
72+
plugins {
73+
id("org.modelix.metamodel.gradle")
74+
}
75+
76+
val mpsVersion: String by rootProject
77+
val modelixCoreVersion: String by rootProject
78+
79+
// ensure that the MPS directory name is correct
80+
val mpsDir = buildDir.resolve("mps")
81+
82+
val mps by configurations.creating
83+
val mpsDependencies by configurations.creating
84+
85+
dependencies {
86+
mps("com.jetbrains:mps:$mpsVersion")
87+
88+
[...]
89+
}
90+
91+
// you might already have this if you use Gradle to build your MPS languages
92+
val resolveMps by tasks.registering(Sync::class) {
93+
from(mps.resolve().map { zipTree(it) })
94+
into(mpsDir)
95+
}
96+
97+
// the specific addition of the meta-model generator Gradle helper
98+
metamodel {
99+
dependsOn(resolveMps)
100+
mpsHome = mpsDir
101+
102+
103+
// Source
104+
105+
// ensure that your languages and solutions you want to generate are listed here
106+
modulesFrom(projectDir.resolve("languages"))
107+
modulesFrom(projectDir.resolve("solutions"))
108+
109+
// further restrictions can be made to filter namespaces, languages or concepts
110+
includeNamespace("org.example")
111+
includeLanguage("language.fq.name")
112+
includeConcept("concept.fq.name")
113+
114+
// this example imports dependencies from the shared dependencies folder
115+
modulesFrom(projectDir.resolve("build/dependencies"))
116+
// and specifically adds repository related concepts
117+
includeLanguage("org.modelix.model.repositoryconcepts")
118+
119+
120+
121+
// Target
122+
123+
// Kotlin
124+
// the target project into which the kotlin API will be build (requires the project to exist in the gradle setup)
125+
kotlinDir = project(":mps:metamodel").projectDir.resolve("src/main/kotlin")
126+
// an alternative to the line above
127+
// kotlinProject = project(":my-kotlin-project")
128+
129+
// you can set the name of the registration helper class here
130+
registrationHelperName = "org.example.MyLanguages"
131+
132+
// TypeScript
133+
// similar to the Kotlin API above, the typescript directory can be set to enable TS API generation
134+
typescriptDir = project(":my-typescript-project").projectDir.resolve("src/gen")
135+
}
136+
137+
[...]
138+
--
139+
140+
. The `org.modelix.metamodel.gradle` Gradle helper provides an additional target which will integrate into your build, so a simple re-build of your Gradle project should be sufficient. Alternatively, you can directly trigger the API generation via
141+
+
142+
[source,bash]
143+
--
144+
./gradlew mps:metamodel:build
145+
--
146+
147+
. Done. You can now use the generated Classes in your code Kotlin (or TypeScript) project in the `mps/metamodel` sub-project.
148+
149+

‎docs/global/modules/core/pages/howto/usage-model-server.adoc‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
= How-To start a local `model-server`
2+
:navtitle: Start a `model-server`
3+
4+
5+
NOTE: If you are interested in a more practical usage of what is presented here, check out the https://github.com/modelix/modelix.samples[samples project^]
6+
7+
8+
- To run the model-server with default configuration run:
9+
+
10+
[source,bash]
11+
--
12+
[modelix.core] $ ./gradlew model-server:run'
13+
--
14+
15+
- To specify a different jdbc configuration, you can add the `-jdbcconf` arguement:
16+
+
17+
[source,bash]
18+
--
19+
[modelix.core] $ ./gradlew model-server:run --args='-jdbcconf path-to-my-database.properties'
20+
--
21+
22+
- During development or to perform tests it is recommended to start the `model-server` with in-memory storage:
23+
+
24+
[source,bash]
25+
--
26+
[modelix.core] $ ./gradlew model-server:run --args='-inmemory'
27+
--
28+

‎docs/global/modules/core/pages/index.adoc‎

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,8 +3,6 @@
33

44
== Introduction
55

6-
TODO
7-
86
include::core:partial$short-description.adoc[]
97

108

‎docs/global/modules/core/pages/reference/component-light-model-client.adoc‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
= Accessing models: The `light-model-client`
2+
:navtitle: `light-model-client`
3+
4+
:tip-caption: 🔗 Quick Links
5+
[TIP]
6+
--
7+
https://artifacts.itemis.cloud/#browse/browse:maven-mps:org%2Fmodelix%2Flight-model-client%2Fmaven-metadata.xml[Nexus^] | https://github.com/modelix/modelix.core[Repository^] | https://github.com/modelix/modelix.core/blob/main/light-model-client/build.gradle.kts[Buildfile^]
8+
--
9+
10+
11+
The `light-model-client` is designed to connect to either an MPS instance or a Modelix `model-server`.
12+
It is implemented in Kotlin multi-platform so that it can also be run in the browser.
13+
14+
15+
// TODO: correct link to advanced model client
16+
While the alternative "advanced model client" provides more features and should be used for long-running processes, the `light-model-client` is optimized for a lower resource consumption and short living processes like in a browser tab.
17+
The server is responsible for resolving conflicts and to keep the client side model in a valid state.

‎docs/global/modules/core/pages/reference/component-metamodel-generator-gradle.adoc‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
= Gradle Helper for the Model API Generator
2+
:navtitle: `metamodel.gradle`
3+
4+
5+
:tip-caption: 🔗 Quick Links
6+
[TIP]
7+
--
8+
https://artifacts.itemis.cloud/#browse/browse:maven-mps:org%2Fmodelix%2Fmetamodel-gradle%2Fmaven-metadata.xml[Nexus^] | https://github.com/modelix/modelix.core[Repository^] | https://github.com/modelix/modelix.core/blob/main/metamodel-gradle/build.gradle.kts[Buildfile^]
9+
--
10+
11+
12+
The `org.modelix.metamodel.gradle` is a Gradle plugin that wraps the functionality of the xref:core:reference/component-metamodel-generator.adoc[meta-model generator].
13+
It provides an additional Gradle task which will apply a 2-saged process:
14+
15+
. MPS meta-model export to YAML
16+
+
17+
In the first step the https://github.com/JetBrains/MPS-extensions[MPS Extensions^] are used to export the MPS structure aspect (i.e. the meta-model) into a YAML file.
18+
In case your meta-model comes from another source this is an external entry point: As long as you can export your meta-model to YAML, you can use the xref:core:reference/component-metamodel-generator.adoc[model API generator]
19+
20+
. YAML to model API generation
21+
+
22+
In the second step, the previously generated YAML file containing the meta-model is generated using the kotlin generator in xref:core:reference/component-metamodel-generator.adoc[]
23+

‎docs/global/modules/core/pages/reference/component-metamodel-generator.adoc‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
= Model API Generator
2+
:navtitle: `metamodel.generator`
3+
4+
5+
:tip-caption: 🔗 Quick Links
6+
[TIP]
7+
--
8+
https://artifacts.itemis.cloud/#browse/browse:maven-mps:org%2Fmodelix%2Fmetamodel-generator%2Fmaven-metadata.xml[Nexus^] | https://github.com/modelix/modelix.core[Repository^] | https://github.com/modelix/modelix.core/blob/main/metamodel-generator/build.gradle.kts[Buildfile^]
9+
--
10+
11+
12+
The `metamodel.generator` is a kotlin components which generates a domain-specific model API.
13+
Currently, the generator supports either Kotlin and TypeScipt as target languages.
14+
As a source for the generated API, the `metamodel.generator` consumes a given meta-model in YAML format.
15+
16+
An example input of the consumed JSON format is as follows
17+
18+
[source,yaml]
19+
--
20+
name: org.modelix.entities
21+
concepts:
22+
- name: Entity
23+
properties:
24+
- name: name
25+
children:
26+
- name: properties
27+
type: Property
28+
multiple: true
29+
optional: true
30+
- name: Property
31+
children:
32+
- name: type
33+
type: Type
34+
optional: false
35+
- name: Type
36+
- name: EntityType
37+
extends:
38+
- Type
39+
references:
40+
- name: entity
41+
type: Entity
42+
optional: false
43+
--
44+

0 commit comments

Comments
 (0)