Initial Documentation

.github/workflows/docu.yml

@@ -0,0 +1,39 @@
+name: docu-wf
+on:
+  push:
+    branches:
+      - 'develop'
+jobs:
+  build-docu:
+    runs-on: ubuntu-24.04
+    defaults:
+      run:
+        working-directory: ./jamopp-ext.doc
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+      - name: Setup Node
+        uses: actions/setup-node@v6
+        with:
+          node-version: 22
+      - name: Build Documentation
+        run: npm ci
+      - run: npm run build
+      - name: Upload Docu Artifacts
+        uses: actions/upload-pages-artifact@v4
+        with:
+          path: build
+  deploy-docu:
+    runs-on: ubuntu-24.04
+    needs: build-docu
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy Docu to GitHub Pages
+        uses: actions/deploy-pages@v4

.github/workflows/nightly_on_develop.yml

@@ -29,4 +29,4 @@ jobs:
           local-source: './p2-jamopp/*'
           remote-target: '${{ env.DEPLOY_PATH }}/nightly'
           release-version: '0.0.0'
-          link-path: ${{ env.DEPLOY_PATH }}
+          link-path: ${{ env.DEPLOY_PATH }}

README.md

@@ -2,41 +2,10 @@
 
 JaMoPP can parse Java source code into EMF-based models and vice versa. It can be used for code analysis and refactoring.
 
-Compared to the original version, the following extensions were made:
-
-- Support for Java 7-15
-- Parsing based on the Eclipse Java Development Tools (JDT)
-- Printing directly based on the meta model
-- Three variants for the reference resolution (based on the Java syntax and/or JDT bindings)
-- Trivial recovery for unresolved references
-
-The current documentation of the extended JaMoPP is available [online at the KIT library](https://publikationen.bibliothek.kit.edu/1000149186).
+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).
 
 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.
 
-# Download / Installation
-
-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:
-
-1. Use the Eclipse Modeling Tools 2022-09 with Java 11 and UTF-8 encoding, and (optionally) install Xtext from the Marketplace.
-2. Clone this repository.
-3. Import all existing plugins of this repository.
-5. Set `releng/org.palladiosimulator.jdt.targetplatform/org.palladiosimulator.jdt.targetplatform.target` as the active target platform.
-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.
-5. Now, JaMoPP should be usable. Please, note: the file encoding needs to be set to UTF-8. Otherwise, there can be compilation errors.
-
-# Building
-
-To build JaMoPP, execute `mvnw clean verify` within the repository to start the Maven build via its wrapper.
-
-# Re-generating the Model Code
-
-If the model code needs to be re-generated, there are the following possibilities:
-
-1. Use the genmodel editor in Eclipse. Please, use only the generation for the model, edit, and editor code (not the test code).
-2. Execute the `clean.mwe2` and `generate.mwe2` files in `releng/org.palladiosimulator.jdt.workflow/wokflow/` if Xtext is installed.
-3. Perform a build.
-
 # Sources on GitHub
 
 [https://github.com/MDSD-Tools/TheExtendedJavaModelParserAndPrinter](https://github.com/MDSD-Tools/TheExtendedJavaModelParserAndPrinter)

jamopp-ext.doc/.gitignore

@@ -0,0 +1,20 @@
+# Dependencies
+/node_modules
+
+# Production
+/build
+
+# Generated files
+.docusaurus
+.cache-loader
+
+# Misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*

jamopp-ext.doc/README.md

@@ -0,0 +1,41 @@
+# Website
+
+This website is built using [Docusaurus 2](https://docusaurus.io/), a modern static website generator.
+
+### Installation
+
+```
+$ npm
+```
+
+### Local Development
+
+```
+$ npm start
+```
+
+This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
+
+### Build
+
+```
+$ npm build
+```
+
+This command generates static content into the `build` directory and can be served using any static contents hosting service.
+
+### Deployment
+
+Using SSH:
+
+```
+$ USE_SSH=true npm deploy
+```
+
+Not using SSH:
+
+```
+$ GIT_USER=<Your GitHub username> npm deploy
+```
+
+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

@@ -0,0 +1,3 @@
+module.exports = {
+  presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
+};

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

@@ -0,0 +1,3 @@
+# Development
+
+Interested in contributing to / developing the extended JaMoPP? Within this section, we provide guidance on its development.

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

@@ -0,0 +1,4 @@
+{
+    "position": 5,
+    "label": "Development"
+}

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

@@ -0,0 +1,54 @@
+---
+sidebar_position: 2
+sidebar_label: Architecture
+---
+
+# Architecture
+
+This document provides an overview over the architecture of the extended JaMoPP. 
+
+```mermaid
+block
+    columns 5
+    space space model space space
+
+    space:5
+
+    model.edit
+    model.edit --> model
+
+    parser
+    parser --> model
+
+    parser.bcel
+    parser.bcel --> model
+
+    resolution
+    resolution --> model
+
+    printer
+    printer --> model
+
+    space:5
+
+    space parser.jdt.singlefile space resource space
+
+    parser.jdt.singlefile --> parser
+    parser.jdt.singlefile --> resolution
+
+    resource --> printer
+    resource --> resolution
+    resource --> parser.jdt.singlefile
+    resource --> parser.bcel
+```
+
+The diagram shows the different components and their connections. Each component corresponds to one Maven module.
+
+* **model** contains the defined metamodel for Java.
+* **model.edit** provides generated code to support edit operations within the EMF.
+* **parser** defines an interface for [parsing Java source code to models](../guides/parsing.md).
+* **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.
+* **parser.bcel** implements the class-to-model converter based on [Apache BCEL](https://commons.apache.org/proper/commons-bcel/).
+* **printer** enables the [printing of models](../guides/printing.md) as Java source code.
+* **resolution** contains the [reference resolution mechanisms](../guides/resolution.md) and [trivial recovery](../guides/recovery.md) for the parsed models.
+* **resource** provides an EMF `Resource` implementation for the extended JaMoPP, combining features from the previous components.

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

@@ -0,0 +1,30 @@
+---
+sidebar_position: 1
+sidebar_label: Setup
+---
+
+# Setup
+
+To setup your system / IDEs for developing the extended JaMoPP, you can follow these instructions.
+
+## Eclipse IDE (for Code)
+
+Currently, only the Eclipse IDE is supported for developing the extended JaMoPP.
+
+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.
+
+   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.
+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.
+1. There are two possibilities to (re-)generate the source code for the metamodel.
+
+   a. Run the build pipeline locally by executing the command `./mvnw clean package` (Linux) or `.\mvnw.cmd clean package` (Windows).
+
+   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).
+
+## For Documentation
+
+The raw content of this documentation is located in the top-level directory `jamopp.doc`. It uses [Docusaurus](https://docusaurus.io/) as documentation framework.
+
+1. Thus, the documentation requires Node.js 18.16.0 or higher installed on your system.
+1. If it is installed, you can run `npm i` in the documentation directory to install the necessary dependencies.
+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.

jamopp-ext.doc/docs/development/workflow.md

@@ -0,0 +1,21 @@
+---
+sidebar_position: 3
+sidebar_label: Workflow
+---
+
+# Workflow
+
+For the development of the extended JaMoPP, we base the workflow on the Gitflow (cf., [the original](https://nvie.com/posts/a-successful-git-branching-model/) or [Atlassian blog post](https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow) for more information).
+
+1. While the `main` branch hosts the source code of all releases with Git tags, all changes are primarily merged into the (default) `develop` branch.
+1. For every bug, feature, release, and other issue, a [GitHub issue](https://github.com/MDSD-Tools/TheExtendedJavaModelParserAndPrinter/issues) needs to be created.
+1. For the resolution of an issue (except releases), there should be a separate feature branch, usually branched from the current `develop` branch, with the name `<issue_number>_<meaningful_short_issue_description_with_words_separated_by_underscores>`. Please consider the `CHANGELOG.md` and this documentation, and update them if necessary.
+1. If the changes are ready for merging, a pull request needs to be created for meging the feature branch into the `develop` branch. It is reviewed by at least one person. After all comments and issues within the pull request are resolved and the pull request is approved, it is merged, closing the pull request and corresponding GitHub issue.
+1. For a release:
+   1. The following parts should be adapted on the `develop` branch:
+      * The version number (at least removing the SNAPSHOT part).
+      * The `CHANGELOG.md`.
+      * The documentation.
+   1. Then, merge `develop` into the `main` branch, and create a tag for the new release.
+   1. Run the `release` GitHub action workflow to build and push the artifacts to the MDSD tools update site and Maven central.
+   1. Update the version number on the `develop` branch once again (select an appropriate higher version number and re-add the SNAPSHOT part).

jamopp-ext.doc/docs/getting-started/README.md

@@ -0,0 +1,5 @@
+# Getting Started
+
+Welcome to the documentation of the extended Java Model Parser and Printer (JaMoPP). It provides tutorials, information about implemented features, and information for developers of JaMoPP.
+
+This section contains tutorials to get started with using the extended JaMoPP.

jamopp-ext.doc/docs/getting-started/_category_.json

@@ -0,0 +1,4 @@
+{
+    "position": 1,
+    "label": "Getting Started"
+}