Skip to content

Commit bf965c0

Browse files
HansMartinAHansMartinA
authored
Merge pull request #31 from MDSD-Tools/10_initial_documentation
Initial Documentation
2 parents 3481374 + 63280b6 commit bf965c0

47 files changed

Lines changed: 20826 additions & 33 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/workflows/docu.yml‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
name: docu-wf
2+
on:
3+
push:
4+
branches:
5+
- 'develop'
6+
jobs:
7+
build-docu:
8+
runs-on: ubuntu-24.04
9+
defaults:
10+
run:
11+
working-directory: ./jamopp-ext.doc
12+
steps:
13+
- name: Checkout
14+
uses: actions/checkout@v6
15+
with:
16+
fetch-depth: 0
17+
- name: Setup Node
18+
uses: actions/setup-node@v6
19+
with:
20+
node-version: 22
21+
- name: Build Documentation
22+
run: npm ci
23+
- run: npm run build
24+
- name: Upload Docu Artifacts
25+
uses: actions/upload-pages-artifact@v4
26+
with:
27+
path: build
28+
deploy-docu:
29+
runs-on: ubuntu-24.04
30+
needs: build-docu
31+
permissions:
32+
pages: write
33+
id-token: write
34+
environment:
35+
name: github-pages
36+
url: ${{ steps.deployment.outputs.page_url }}
37+
steps:
38+
- name: Deploy Docu to GitHub Pages
39+
uses: actions/deploy-pages@v4

‎.github/workflows/nightly_on_develop.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -29,4 +29,4 @@ jobs:
2929
local-source: './p2-jamopp/*'
3030
remote-target: '${{ env.DEPLOY_PATH }}/nightly'
3131
release-version: '0.0.0'
32-
link-path: ${{ env.DEPLOY_PATH }}
32+
link-path: ${{ env.DEPLOY_PATH }}

‎README.md‎

Lines changed: 1 addition & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -2,41 +2,10 @@
22

33
JaMoPP can parse Java source code into EMF-based models and vice versa. It can be used for code analysis and refactoring.
44

5-
Compared to the original version, the following extensions were made:
6-
7-
- Support for Java 7-15
8-
- Parsing based on the Eclipse Java Development Tools (JDT)
9-
- Printing directly based on the meta model
10-
- Three variants for the reference resolution (based on the Java syntax and/or JDT bindings)
11-
- Trivial recovery for unresolved references
12-
13-
The current documentation of the extended JaMoPP is available [online at the KIT library](https://publikationen.bibliothek.kit.edu/1000149186).
5+
The current documentation of the extended JaMoPP is available [online on GitHub Pages](https://MDSD-Tools.github.io/TheExtendedJavaModelParserAndPrinter) and [in this repository](./jamopp-ext.doc/docs) (as raw Markdown).
146

157
The extended version is developed by the Institute of Information Security and Dependability (KASTEL) at the Karlsruher Institute of Technology (KIT). This repository is not endorsed by or affiliated with DevBoost GmbH or Software Technology Group, Dresden University of Technology.
168

17-
# Download / Installation
18-
19-
Currently, JaMoPP can be installed from its [update site](https://updatesite.palladio-simulator.com/palladio-supporting-eclipsejavadevelopmenttools/nightly/), or the plugins can be directly imported into Eclipse:
20-
21-
1. Use the Eclipse Modeling Tools 2022-09 with Java 11 and UTF-8 encoding, and (optionally) install Xtext from the Marketplace.
22-
2. Clone this repository.
23-
3. Import all existing plugins of this repository.
24-
5. Set `releng/org.palladiosimulator.jdt.targetplatform/org.palladiosimulator.jdt.targetplatform.target` as the active target platform.
25-
4. In `releng/org.palladiosimulator.jdt.workflow/workflow/`, execute the `generate.mwe2` file (if Xtext is installed). Alternatively, execute a build in which the model code is also generated.
26-
5. Now, JaMoPP should be usable. Please, note: the file encoding needs to be set to UTF-8. Otherwise, there can be compilation errors.
27-
28-
# Building
29-
30-
To build JaMoPP, execute `mvnw clean verify` within the repository to start the Maven build via its wrapper.
31-
32-
# Re-generating the Model Code
33-
34-
If the model code needs to be re-generated, there are the following possibilities:
35-
36-
1. Use the genmodel editor in Eclipse. Please, use only the generation for the model, edit, and editor code (not the test code).
37-
2. Execute the `clean.mwe2` and `generate.mwe2` files in `releng/org.palladiosimulator.jdt.workflow/wokflow/` if Xtext is installed.
38-
3. Perform a build.
39-
409
# Sources on GitHub
4110

4211
[https://github.com/MDSD-Tools/TheExtendedJavaModelParserAndPrinter](https://github.com/MDSD-Tools/TheExtendedJavaModelParserAndPrinter)

‎jamopp-ext.doc/.gitignore‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Dependencies
2+
/node_modules
3+
4+
# Production
5+
/build
6+
7+
# Generated files
8+
.docusaurus
9+
.cache-loader
10+
11+
# Misc
12+
.DS_Store
13+
.env.local
14+
.env.development.local
15+
.env.test.local
16+
.env.production.local
17+
18+
npm-debug.log*
19+
yarn-debug.log*
20+
yarn-error.log*

‎jamopp-ext.doc/README.md‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
# Website
2+
3+
This website is built using [Docusaurus 2](https://docusaurus.io/), a modern static website generator.
4+
5+
### Installation
6+
7+
```
8+
$ npm
9+
```
10+
11+
### Local Development
12+
13+
```
14+
$ npm start
15+
```
16+
17+
This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
18+
19+
### Build
20+
21+
```
22+
$ npm build
23+
```
24+
25+
This command generates static content into the `build` directory and can be served using any static contents hosting service.
26+
27+
### Deployment
28+
29+
Using SSH:
30+
31+
```
32+
$ USE_SSH=true npm deploy
33+
```
34+
35+
Not using SSH:
36+
37+
```
38+
$ GIT_USER=<Your GitHub username> npm deploy
39+
```
40+
41+
If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.

‎jamopp-ext.doc/babel.config.js‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
module.exports = {
2+
presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
3+
};

‎jamopp-ext.doc/docs/development/README.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# Development
2+
3+
Interested in contributing to / developing the extended JaMoPP? Within this section, we provide guidance on its development.

‎jamopp-ext.doc/docs/development/_category_.json‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
{
2+
"position": 5,
3+
"label": "Development"
4+
}

‎jamopp-ext.doc/docs/development/architecture.md‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
---
2+
sidebar_position: 2
3+
sidebar_label: Architecture
4+
---
5+
6+
# Architecture
7+
8+
This document provides an overview over the architecture of the extended JaMoPP.
9+
10+
```mermaid
11+
block
12+
columns 5
13+
space space model space space
14+
15+
space:5
16+
17+
model.edit
18+
model.edit --> model
19+
20+
parser
21+
parser --> model
22+
23+
parser.bcel
24+
parser.bcel --> model
25+
26+
resolution
27+
resolution --> model
28+
29+
printer
30+
printer --> model
31+
32+
space:5
33+
34+
space parser.jdt.singlefile space resource space
35+
36+
parser.jdt.singlefile --> parser
37+
parser.jdt.singlefile --> resolution
38+
39+
resource --> printer
40+
resource --> resolution
41+
resource --> parser.jdt.singlefile
42+
resource --> parser.bcel
43+
```
44+
45+
The diagram shows the different components and their connections. Each component corresponds to one Maven module.
46+
47+
* **model** contains the defined metamodel for Java.
48+
* **model.edit** provides generated code to support edit operations within the EMF.
49+
* **parser** defines an interface for [parsing Java source code to models](../guides/parsing.md).
50+
* **parser.jdt.singlefile** implements the interface from the **parser** component by parsing Java source code with the Eclipse Java Development Tools (JDT) and converting the resulting ASTs to models. This component also supports the parsing of single files without all dependencies.
51+
* **parser.bcel** implements the class-to-model converter based on [Apache BCEL](https://commons.apache.org/proper/commons-bcel/).
52+
* **printer** enables the [printing of models](../guides/printing.md) as Java source code.
53+
* **resolution** contains the [reference resolution mechanisms](../guides/resolution.md) and [trivial recovery](../guides/recovery.md) for the parsed models.
54+
* **resource** provides an EMF `Resource` implementation for the extended JaMoPP, combining features from the previous components.

‎jamopp-ext.doc/docs/development/setup.md‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
---
2+
sidebar_position: 1
3+
sidebar_label: Setup
4+
---
5+
6+
# Setup
7+
8+
To setup your system / IDEs for developing the extended JaMoPP, you can follow these instructions.
9+
10+
## Eclipse IDE (for Code)
11+
12+
Currently, only the Eclipse IDE is supported for developing the extended JaMoPP.
13+
14+
1. The code requires Java 17 and the Eclipse Modeling Tools 2022-12 with the Maven plugin (needs manual installation) since the project is organized with pure Maven modules.
15+
16+
Hint: You can install the Maven plugin by opening the software installation panel (menu "Help" -> "Install New Software"). Then, you can show a list of update sites for the field "Work with:". From this list, select "2022-12 - https://download.eclipse.org/releases/2022-12", search for "Maven", and select "M2E - Maven Integration for Eclipse" for installation. Afterward, proceed with the installation.
17+
1. After Eclipse is prepared, the Maven modules of the extended JaMoPP can be easily imported from the top-level directory into Eclipse. However, the source code for the Java metamodel is not generated yet.
18+
1. There are two possibilities to (re-)generate the source code for the metamodel.
19+
20+
a. Run the build pipeline locally by executing the command `./mvnw clean package` (Linux) or `.\mvnw.cmd clean package` (Windows).
21+
22+
b. In Eclipse, open the file `jamopp.model/src/main/resources/metamodel/java.genmodel`, and execute `Generate Model` (available on right click on "Java" if the EMF Generator editor is opened and only showing a tree view).
23+
24+
## For Documentation
25+
26+
The raw content of this documentation is located in the top-level directory `jamopp.doc`. It uses [Docusaurus](https://docusaurus.io/) as documentation framework.
27+
28+
1. Thus, the documentation requires Node.js 18.16.0 or higher installed on your system.
29+
1. If it is installed, you can run `npm i` in the documentation directory to install the necessary dependencies.
30+
1. Then, `npm start` opens the generated documentation in the browser (defaults to `http://localhost:3000`), which is automatically updated on changes in the documentation files.

0 commit comments

Comments
 (0)