Documentation Workflow (#220)

.github/workflows/docs.yml

@@ -2,6 +2,9 @@ name: Documentation
 
 on:
   push:
+    branches: 
+      - main
+    tags: "v**"
     paths:
       - 'docs/**'
       - '.github/workflows/docs.yml'
@@ -11,30 +14,23 @@ jobs:
   docs:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
-      - name: Fix Deployment for GH Pages
-        run: mkdir -p docs/_build/dirhtml/ && touch docs/_build/dirhtml/.nojekyll
-      - uses: joshlong/java-version-export-github-action@v28
-        id: jve
-      - name: Set up JDK
-        uses: actions/setup-java@v3
+      - uses: actions/[email protected]
         with:
-          distribution: 'temurin'
-          java-version: ${{ steps.jve.outputs.java_major_version }}
-          cache: 'maven'
-      - uses: actions/setup-python@v4
+          token: ${{ secrets.PAT_TOKEN }}
+      - uses: actions/[email protected]
         with:
-          python-version: '3.9'
-
-      - run: pip install -r requirements.txt && sudo apt update && sudo apt install graphviz -y
-        working-directory: docs
-      - run: make html dirhtml
-        working-directory: docs
-
+          repository: ${{ github.repository }}.wiki
+          path: wiki
+          token: ${{ secrets.PAT_TOKEN }}
+
+      - name: Remove contents in Wiki
+        working-directory: wiki
+        run: ls -A1 | grep -v '.git' | xargs rm -r
+
+      - name: Copy Wiki from Docs folder
+        run: cp -r ./docs/. ./wiki
+
       - name: Deploy 🚀
-        if: github.ref == 'refs/heads/main'
-        uses: JamesIves/[email protected]
+        uses: stefanzweifel/git-auto-commit-action@v4
         with:
-          branch: gh-pages
-          folder: docs/_build/dirhtml/
-          clean: true
+          repository: wiki

.gitignore

@@ -1,3 +1,4 @@
+wiki
 .flattened-pom.xml
 
 tests/src/test/resources/testout/*

README.md

@@ -25,7 +25,7 @@ Future user interfaces like a Graphical User Interface (GUI) or a web interface
 
 ## Documentation
 
-For more information about the setup or the architecture have a look on the [docs](https://ardoco.github.io/Core).
+For more information about the setup or the architecture have a look on the [Wiki](https://github.com/ArDoCo/Core/wiki).
 The docs are at some points deprecated, the general overview and setup should still hold.
 You can find the generated JavaDocs at [ArDoCo.github.io/Core-Docs](https://ArDoCo.github.io/Core-Docs/).
 
@@ -43,7 +43,7 @@ To test the Core, you could use case studies and benchmarks provided in ..
 	<dependency>
 		<groupId>io.github.ardoco.core</groupId>
 		<artifactId>pipeline</artifactId> <!-- or any other subproject -->
-		<version>0.7.0-SNAPSHOT</version>
+		<version>VERSION</version>
 	</dependency>
 </dependencies>
 ```

docs/Home.md

@@ -0,0 +1,23 @@
+ArDoCo (Architecture Documentation Consistency) is a framework to connect architecture documentation and models while identifying missing or deviating elements (inconsistencies). An element can be any representable item of the model, like a component or a relation. To do so, ArDoCo first creates trace links and then makes use of them and other information to identify inconsistencies.
+
+You can find [ArDoCo on GitHub](https://github.com/ArDoCo).
+
+Before contributing, please read the [Quickstart Guide](quickstart).
+
+JavaDocs can be found [here](https://ardoco.github.io/Core-Docs/).
+
+## Case Studies & Benchmarks
+You can test ArDoCo using our case studies and benchmarks provided in ...
+
+* [Case Studies](https://github.com/ArDoCo/SWATTR)
+* [Benchmarks](https://github.com/ArDoCo/Benchmark)
+
+## Publications
+Trace Link Recovery for Software Architecture Documentation Keim, J.; Schulz, S.; Fuchß, D.; Kocher, C.; Speit, J.; Koziolek, A. 2021. Software Architecture: 15th European Conference, ECSA 2021, Virtual Event, Sweden, September 13-17, 2021, Proceedings. Ed.: S. Biffl, 101–116, Springer Verlag. [doi:10.1007/978-3-030-86044-8_7](https://doi.org/10.1007/978-3-030-86044-8_7)
+
+The initial version of ArDoCo is based on the master thesis [Linking Software Architecture Documentation and Models](https://publikationen.bibliothek.kit.edu/1000126194).
+
+## Contact
+This project is currently developed by researchers of the Karlsruhe Institute of Technology.
+
+You find us on our websites: [Jan Keim](https://mcse.kastel.kit.edu/staff_Keim_Jan.php), [Sophie Corallo](https://mcse.kastel.kit.edu/staff_sophie_corallo.php), and [Dominik Fuchß](https://mcse.kastel.kit.edu/staff_dominik_fuchss.php)

docs/Profiles.md

@@ -0,0 +1,29 @@
+ArDoCo uses maven profiles to provide subsets of its functionality and speed up development time.
+
+## Current Profiles
+
+* **complete** (activated by default)
+* **deployment** (profile for deployment to maven central)
+* **tlr** (profile for traceability link recovery)
+* **inconsistency** (profile for inconsistency detection)
+
+## Adding new profiles
+In order to add a new profile, you have to extend the profile section in the main pom.xml (as well as in all submodules that contain submodules; i.e., stages, tests)
+
+```xml
+    <profile>
+      <!-- Name of the new Profile -->
+      <id>new-profile-id</id>
+      <activation>
+        <activeByDefault>false</activeByDefault>
+      </activation>
+      <modules>
+        <module>framework</module>
+        <module>pipeline</module>
+        <module>stages</module>
+        <module>tests</module>
+      </modules>
+    </profile>
+```
+
+

docs/Quickstart.md

@@ -0,0 +1,114 @@
+The ArDoCo-Core is a maven project and can be embedded by using its specs (from the [pom](https://github.com/ArDoCo/Core/blob/main/pom.xml)).
+
+You can run and configure the execution with the CLI.
+
+Please acknowledge the [code of conduct](https://github.com/ArDoCo/Core/blob/main/CODE_OF_CONDUCT.md).
+
+## Forking the project & submitting pull requests
+This project uses Sonarcloud to check code quality. There are Github Actions that automatically verify the build and generate a Sonarcloud-report. Additionally, pull requests are automatically checked. If the build fails or the Quality Gate is not passed, it is marked in the Pull Request and you need to fix the PR until it passes. Otherwise, the PR won’t get merged.
+
+If you fork the project, make sure to create a Sonarcloud token to make sure everything works for you and the Sonarcloud check does not fail. You need to enable Sonarcloud for you and add a Sonarcloud token to the repository of the fork as secret.
+
+Follow the following steps to do so:
+
+* Log into SonarCloud and click on your profile and then go to My Account and then Security. Alternatively go directly to account/security.
+* Generate your access token for SonarCloud and copy it. The access token will be provided to the build pipeline as a secret environment variable.
+* Go to your repository settings in Github, then to Secrets
+* Add a new secret with name SONAR_TOKEN and the value of the just generated access token.
+
+### Formatter
+Please use the provided [formatter](https://github.com/ArDoCo/Core/blob/main/formatter.xml) when contributing.
+
+Additionally, make use of the spotless-plugin for maven to format your code. You can run it via mvn spotless:apply ([more info](https://github.com/diffplug/spotless/tree/main/plugin-maven)).
+
+### Documentation
+⚠️ WIP
+
+## Command Line Interface (CLI)
+[ArDoCo CLI](https://github.com/ArDoCo/CLI) contains a CLI that supports the execution of ArDoCo.
+
+It is necessary to specify an input model as well as a textual documentation. Usually, our model is an architectural model. However, the model can also contain a (Java) code model that you can insert using the [CodeModelExtractors](https://github.com/ArDoCo/Core/tree/main/framework/java-model-extractor).
+
+All results (trace links, inconsistencies, etc. between the input model and documentation) are written to the specified output location.
+
+The [CLI](https://github.com/ArDoCo/CLI/blob/main/src/main/java/edu/kit/kastel/mcse/ardoco/core/pipeline/ArDoCoCLI.java) is part of the [CLI project](https://github.com/ArDoCo/CLI) of ArDoCo.
+
+## Standard Configuration
+⚠️ WIP
+
+## Save Actions (Eclipse)
+Go to your Eclipse Workspace folder and open the file `.metadata/.plugins/org.eclipse.core.runtime/.settings/org.eclipse.jdt.ui.prefs`.
+There, exchange all the `sp_cleanup.` properties to the following:
+
+```
+sp_cleanup.add_default_serial_version_id=true
+sp_cleanup.add_generated_serial_version_id=false
+sp_cleanup.add_missing_annotations=true
+sp_cleanup.add_missing_deprecated_annotations=true
+sp_cleanup.add_missing_methods=false
+sp_cleanup.add_missing_nls_tags=false
+sp_cleanup.add_missing_override_annotations=true
+sp_cleanup.add_missing_override_annotations_interface_methods=true
+sp_cleanup.add_serial_version_id=false
+sp_cleanup.always_use_blocks=true
+sp_cleanup.always_use_parentheses_in_expressions=true
+sp_cleanup.always_use_this_for_non_static_field_access=false
+sp_cleanup.always_use_this_for_non_static_method_access=false
+sp_cleanup.convert_functional_interfaces=true
+sp_cleanup.convert_to_enhanced_for_loop=true
+sp_cleanup.convert_to_enhanced_for_loop_if_loop_var_used=false
+sp_cleanup.correct_indentation=true
+sp_cleanup.format_source_code=true
+sp_cleanup.format_source_code_changes_only=false
+sp_cleanup.insert_inferred_type_arguments=false
+sp_cleanup.lazy_logical_operator=false
+sp_cleanup.make_local_variable_final=true
+sp_cleanup.make_parameters_final=false
+sp_cleanup.make_private_fields_final=true
+sp_cleanup.make_type_abstract_if_missing_method=false
+sp_cleanup.make_variable_declarations_final=false
+sp_cleanup.merge_conditional_blocks=false
+sp_cleanup.never_use_blocks=false
+sp_cleanup.never_use_parentheses_in_expressions=false
+sp_cleanup.number_suffix=true
+sp_cleanup.on_save_use_additional_actions=true
+sp_cleanup.organize_imports=true
+sp_cleanup.push_down_negation=false
+sp_cleanup.qualify_static_field_accesses_with_declaring_class=false
+sp_cleanup.qualify_static_member_accesses_through_instances_with_declaring_class=true
+sp_cleanup.qualify_static_member_accesses_through_subtypes_with_declaring_class=true
+sp_cleanup.qualify_static_member_accesses_with_declaring_class=false
+sp_cleanup.qualify_static_method_accesses_with_declaring_class=false
+sp_cleanup.remove_private_constructors=true
+sp_cleanup.remove_redundant_modifiers=true
+sp_cleanup.remove_redundant_semicolons=true
+sp_cleanup.remove_redundant_type_arguments=true
+sp_cleanup.remove_trailing_whitespaces=true
+sp_cleanup.remove_trailing_whitespaces_all=true
+sp_cleanup.remove_trailing_whitespaces_ignore_empty=false
+sp_cleanup.remove_unnecessary_array_creation=false
+sp_cleanup.remove_unnecessary_casts=true
+sp_cleanup.remove_unnecessary_nls_tags=false
+sp_cleanup.remove_unused_imports=true
+sp_cleanup.remove_unused_local_variables=false
+sp_cleanup.remove_unused_private_fields=true
+sp_cleanup.remove_unused_private_members=false
+sp_cleanup.remove_unused_private_methods=true
+sp_cleanup.remove_unused_private_types=true
+sp_cleanup.simplify_lambda_expression_and_method_ref=false
+sp_cleanup.sort_members=false
+sp_cleanup.sort_members_all=false
+sp_cleanup.use_anonymous_class_creation=false
+sp_cleanup.use_autoboxing=true
+sp_cleanup.use_blocks=true
+sp_cleanup.use_blocks_only_for_return_and_throw=false
+sp_cleanup.use_directly_map_method=false
+sp_cleanup.use_lambda=true
+sp_cleanup.use_parentheses_in_expressions=false
+sp_cleanup.use_this_for_non_static_field_access=true
+sp_cleanup.use_this_for_non_static_field_access_only_if_necessary=true
+sp_cleanup.use_this_for_non_static_method_access=true
+sp_cleanup.use_this_for_non_static_method_access_only_if_necessary=true
+sp_cleanup.use_unboxing=true
+sp_cleanup.use_var=false
+```