Doc WIP

README.md

@@ -4,6 +4,22 @@
 
 This project is a minimal setup running the MontiSim simulator in a local self-contained jar.
 
+### Quickstart
+
+If you know about MontiSim and Maven, the following will suffice you:
+
+> ```
+> git clone https://git.rwth-aachen.de/monticore/EmbeddedMontiArc/simulators/basic-simulator
+> cd basic-simulator
+> mvn clean install -s settings.xml
+> ```
+> The resulting jar (`target/basic-simulator-1.*.jar`) can be launched normally in any folder and will create
+> the required sub-folders and export the needed libraries.
+
+> The `build_install` script build the project and puts the jar in the `install` folder, which contains a sample setup.
+
+If not, the following documents aim at giving an introduction to project building, Maven, scripts and MontiSim.
+
 ### Documentation Contents
 
 - [Installing and using the Basic Simulator](docs/usage.md)

docs/maven.md

@@ -7,6 +7,28 @@ Prev: [Installing and using the Basic Simulator](docs/usage.md)    |    Next: [S
 
 *Comming Soon*
 
+> - Git recap
+>   - Branches, local repos, commits, push/pull.
+>   - Merge requests
+> - Maven project: pom file and project structure
+>   - Pom file: 
+>     - describes the project name and version
+>     - dependencies
+>     - importing into maven
+>   - Project structure:
+>     - sources under src/main or src/test -> used by maven for the resulting jar / for the tests.
+>     - java or resources folder
+>     - docs / scripts / utility folders
+>     - target folder: contains all the results of the build, including the jar.
+>     - Packaging: try to use consistent package structure.
+> - Maven dependency system: nexus, local repository and versioning
+>   - Nexus: from the SE chair, contains all the versions from the master branch. Linked to in settings.xml.
+>   - Local repository: (.m2/repository under windows) contains the dependencies from the nexus + the projects compiled using the "install" target: you can override versions/...
+>   - Versioning: use next version with -SNAPSHOT when developing in a branch. Refer to this version locally. The commit that will be merged to master must NOT contain the -SNAPSHOT.
+> - Maven plug-ins: build targets and plug-ins
+> - Gitlab CI and other Repository plug-ins
+>   - CI stages, runners
+
 
 ---
 

docs/scripts.md

@@ -8,6 +8,11 @@ Prev: [Maven Project tutorial](docs/maven.md)    |    Next: [MontiSim overview](
 *Comming Soon*
 
 
+> - Recommendation: create scripts to automate processes that take more than one short step.
+> - Cheatsheet: most usefull commands under linux and windows.
+> - Use cases: building, inter-project copy, testing.
+
+
 ---
 
 Prev: [Maven Project tutorial](docs/maven.md)    |    Next: [MontiSim overview](docs/montisim.md)

docs/usage.md

@@ -10,13 +10,13 @@ Next: [Maven Project tutorial](maven.md)
 
 This repository is a [Maven](https://maven.apache.org/) project.
 
-In a folder (we recommend making a "MontiSim" folder containing all the cloned projects), clone the repository using the following in the terminal:
+In a folder (we recommend making a "MontiSim" folder containing all the cloned projects), clone the repository using the following in the console:
 ```batch
 git clone https://git.rwth-aachen.de/monticore/EmbeddedMontiArc/simulators/basic-simulator
 ```
 This will create a folder named `basic-simulator` and download the contents of this repository inside.
 
-> **NOTE**: To open a console rapidly in windows, type "cmd" in the navigation bar of the windows explorer and press *Enter*.
+> **NOTE**: To open a console in a specific working directory rapidly in windows, type "cmd" in the navigation bar of the windows explorer and press *Enter*.
 > Choose *Right Clic -> Open in terminal* on the folder under Linux.
 >
 > ![Select the navigation bar.](images/cmd1.png "Select the navigation bar.")
@@ -46,28 +46,29 @@ java -jar basic-simulator.jar
 ```
 
 This will open a window listing the available **autopilots**, **maps**, **scenarios** and simulation **results**. These are 
-located alongside the basic-simulator jar inside folders with the same names.
+located alongside the `basic-simulator.jar` file inside folders with the same names.
 
 By selecting a **scenario**, you can press the "Start Simulation" button to run this scenario in the simulator.
 
-![Scenario select.](images/usage.png "Select a scenario and press the button.")
-
-**NOTE**: *Currently the output of the simulation is only shown in the console.*
+> ![Scenario select.](images/usage.png "Select a scenario and press the button.")
+> 
+> **NOTE**: *Currently the output of the simulation is only shown in the console.*
 
 You can start a simulation directly without interacting with the GUI by passing a scenario name as command line argument
 to the simulator:
 ```batch
 java -jar basic-simulator.jar straight
 ```
-> *This would start a simulation directly with the scenario "straight"*
-> 
-> *This can be used in a script as well*
+> - *This would start a simulation directly with the scenario "straight"*
+> - *This can be used in a script as well*
 
 ## Scenario format
 
-The Basic Simulator uses **JSON** scenarios. This is for easier prototyping and parsing of the scenarios. The scenario "straight" is a good
-example of how to configure a scenario. For the complete configuration entries currently supported, look at the entries in the `BasicController.ScenarioSettings` enum.
-The configuration specific to vehicles can be seen in `VehicleBuilder.VehicleSettings`.
+The Basic Simulator uses **JSON** scenarios. This is for easier prototyping and parsing of the scenarios. The scenario [straight](../install/scenarios/straight.json) is a good
+example of how to configure a scenario. For the complete configuration entries currently supported, look at the entries in the 
+[BasicController.ScenarioSettings](../src/main/java/de/rwth_aachen/se/montisim/simulators/basic_simulator/controller/BasicController.java#L35) enum.
+The configuration specific to vehicles can be seen in 
+[VehicleBuilder.VehicleSettings](../src/main/java/de/rwth_aachen/se/montisim/simulators/basic_simulator/controller/VehicleBuilder.java#L72).
 
 ## Working on Maven projects