Merge pull request #93 from FS-Online/docs-versioning

Docs improvements running up to beta release

.gitignore

@@ -1,9 +1,6 @@
 .vscode/
 operator/logs/
 
-# mkdocs expects a README.md placed in the docs/ folder as the primary page. Since this is just a copy it shoudn't be committed.
-docs/README.md
-
 # Inside the simulator folder the compiled version of the UE4Project will be placed which shouldn't be committed.
 simulator/
 !simulator/readme.md

README.md

@@ -3,9 +3,9 @@
 
 [Read the docs here.](https://fs-online.github.io/Formula-Student-Driverless-Simulator/)
 
-This is a Formula Student Driverless Simulation Competition System (FSDS).
+This is a Formula Student Driverless Simulator (FSDS).
 It will provide a virtual environment where Autonomous Systems from different Formula Student teams can compete in time-trial challenges. 
-The first competition will take place during the driverless event, FS-Online 2020.
+The first competition will take place during the driverless event, [FS-Online 2020](https://formulastudentonline.com/).
 
 FSDS is brought to you by your friends at Formula Student Team Delft, MIT Driverless and FSEast.
 

docs/README.md

@@ -0,0 +1,15 @@
+# Formula Student Driverless Simulator
+
+Welcome to the FSDS documentation.
+
+This home page contains an index with a brief description of the different sections in the documentation. 
+Feel free to read in whatever order preferred. 
+In any case, here are a few suggestions for newcomers.
+
+* **Get familiar with the architecture.** The [system overview](system-overview.md) introduces you to the ideas and concepts of the system.
+* **Run the simulation.** Either follow the [simulation guide](how-to-simulate.md) or build from source by following the [development guide](how-to-develop.md)
+* **Integrate ROS.** [Build the ros bridge node](building-ros.md) and [launch the ros bridge](ros-bridge.md)
+
+## Participating in FS-Online 2020?
+Participants of the FS-Online 2020 virtual event should start by reading the [system overview](system-overview.md) and [integration handbook](integration-handbook.md).
+Next, follow the steps in [the simulation guide](how-to-simulate.md) to get your simulation up and running.

docs/css/version-select.css

@@ -0,0 +1,5 @@
+#version-selector {
+  display: block;
+  margin: -10px auto 0.809em;
+  padding: 2px;
+}

docs/get-ready-to-develop.md

@@ -7,6 +7,7 @@ Using this tutorial you can set up your computer to development the simulator.
 
 For developing this project, you need quite a good computer because Unreal Engine is a heavy baby.
 We highly recommend the following computer specs. You might be able to run with less power but everything will be slower.
+
 * 8 core 3Ghz CPU
 * 12 GB memory
 * 100GB free SSD storage
@@ -33,9 +34,11 @@ Launch the epic installer and install Unreal Engine 4.25
 [Download visual studio 2019 (community edition)](https://visualstudio.microsoft.com/vs/)
 
 During installation, choose the following components:
+
 * Desktop development with C++
 * Game development with C++
 * Linux development with C++
+
 At 'Invidual Components select:
 * C++ CMake tools for Windows
 * Windows 10 SDK 10.0.18.362.0

docs/gps.md

@@ -18,5 +18,5 @@ Currently the eph is set to **4 cm**.
 This noise, however, is only added if the measured velocity is above an arbitrarily chosen threshold (currently 0.1m/s). 
 To velocities below that, this additional inaccuracy is not introduced to avoid “jumpy” positions during standstill of the vehicle. 
 
-See [GpsSimple.hpp](/AirSim/AirLib/include/sensors/gps/GpsSimple.hpp) and [GpsSimpleParams.hpp](/AirSim/AirLib/include/sensors/gps/GpsSimpleParams.hpp) for the implementation of the gps model.
+See GpsSimple.hpp (/AirSim/AirLib/include/sensors/gps/GpsSimple.hpp) and [GpsSimpleParams.hpp](/AirSim/AirLib/include/sensors/gps/GpsSimpleParams.hpp) for the implementation of the gps model.
 

docs/how-to-develop.md

@@ -54,3 +54,13 @@ Now you can [run the ros bridge](ros-bridge.md).
 4. Wait until it finishes.
 5. Go into the `WindowsNoEditor` folder and rename `Blocks.exe` to `FSDS.exe`
 6. Zip all files and upload to github release!
+
+## Deploying documentation
+For documentation we use [mkdocs](https://www.mkdocs.org/) and [mike](https://github.com/jimporter/mike/).
+Hosting is provided by github pages. 
+
+To tag a new version of the documentation and release it to github, first checkout the version that you want to deploy.
+Then run `mike deploy VERSION latest -u -p`.
+This will compile the documentation, store it as a new version in the `gh-pages` branch, update teh `latest` alias to point at the new version and push the `gh-pages` branch to github and thus making the documentation public.
+To create a new version without updating the `latest` tag, omit the `latest -u` part. 
+

docs/how-to-simulate.md

@@ -3,6 +3,7 @@
 
 To run the simulation smoothly you need quite a fast windows computer with a modern videocard.
 Minimally you will need:
+
 * 8 core 2.3Ghz CPU
 * 12 GB memory
 * 30GB free SSD storage
@@ -13,15 +14,14 @@ To check the video card drivers, run `vulkaninfo`. It should output a bunch of l
 ## Launching the simulator
 To launch the simulator, go to [releases](https://github.com/FS-Online/Formula-Student-Driverless-Simulator/releases) and download the latest one.
 
-Before you start, you have to create the folder and file `Formula-Student-Driverless-Simulator/settings.json` in your home directory.
+Before you start, you have to create the folder and file `Formula-Student-Driverless-Simulator/settings.json` in your **home directory**.
 This file contains the sensor configuration of the car.
-You should create a folder in your **home directory** called `Formula-Student-Driverless-Simulator`. 
-Inside the folder `Formula-Student-Driverless-Simulator` create a file called `settings.json` and copy-paste the contents of the settings.json file at the root of this repository inside.
+Copy-paste the contents of the [settings.json file at the root of this repository](https://github.com/FS-Online/Formula-Student-Driverless-Simulator/blob/master/settings.json) inside.
 This should get you started with the default sensor configuration, feel free to try your own custom sensor suite.
 Note that the naming of the sensors will be reflected in the topic names as elaborated [here](ros-bridge.md).
 
 Now launch FSDS.exe and a window with a car should popup!
-Try to drive the car around by using the arrowkeys.
+Try driving the car around using the arrowkeys.
 
 ## Launching the ROS bridge
 To connect your autonomous ROS system, you have to clone this repository and run the `fsds_ros_bridge` ROS node.

docs/imu.md

@@ -10,7 +10,7 @@ The angular velocity, linear acceleration outputs as well as their biases have a
 
 All of the IMU measurements are timestamped.
 
-See [ImuSimple.hpp](/AirSim/AirLib/include/sensors/imu/ImuSimple.hpp) and [ImuSimpleParams.hpp](/AirSim/AirLib/include/sensors/imu/ImuSimpleParams.hpp) for the implementation of the IMU model.
+See ImuSimple.hpp (/AirSim/AirLib/include/sensors/imu/ImuSimple.hpp) and [ImuSimpleParams.hpp] /AirSim/AirLib/include/sensors/imu/ImuSimpleParams.hpp for the implementation of the IMU model.
 
 
 

docs/integration-handbook.md

@@ -36,6 +36,7 @@ During the competition, on each track, every AS will do an autocross mission bef
 It can occur that multiple autocross runs on different tracks take place before going to trackdrive.
 It can also happen that multiple autocross runs take place on the same track.
 For example, the AS might be requested to do:
+
 1. autocross on track A
 2. autocross on track B
 3. trackdrive on track A
@@ -155,21 +156,21 @@ Most of the parameters in the settings.json file will be set by the officials to
 You are allowed to configure the following subset of parameters within the boundaries of the above rules.
 
 * Cameras   
-   * camera name
-   * Width, Height
-   * FOV_Degrees
-   * X, Y, Z
-   * Pitch, Roll, Yaw
+ *  * camera name
+ *  * Width, Height
+ *  * FOV_Degrees
+ *  * X, Y, Z
+ *  * Pitch, Roll, Yaw
 * Lidars
-   * NumberOfChannels
-   * PointsPerSecond
-   * RotationsPerSecond
-   * HorizontalFOVStart
-   * HorizontalFOVEnd
-   * VerticalFOVUpper
-   * VerticalFOVLower
-   * X, Y, Z
-   * Pitch, Roll, Yaw
+ *  * NumberOfChannels
+ *  * PointsPerSecond
+ *  * RotationsPerSecond
+ *  * HorizontalFOVStart
+ *  * HorizontalFOVEnd
+ *  * VerticalFOVUpper
+ *  * VerticalFOVLower
+ *  * X, Y, Z
+ *  * Pitch, Roll, Yaw
 
 The GPS and IMU are configured equally for all teams according to the rules in the previous chapter.
 

docs/js/version-select.js

@@ -0,0 +1,64 @@
+window.addEventListener("DOMContentLoaded", function() {
+  function normalizePath(path) {
+    var normalized = [];
+    path.split("/").forEach(function(bit, i) {
+      if (bit === "." || (bit === "" && i !== 0)) {
+        return;
+      } else if (bit === "..") {
+        if (normalized.length === 1 && normalized[0] === "") {
+          // We must be trying to .. past the root!
+          throw new Error("invalid path");
+        } else if (normalized.length === 0 ||
+                   normalized[normalized.length - 1] === "..") {
+          normalized.push("..");
+        } else {
+          normalized.pop();
+        }
+      } else {
+        normalized.push(bit);
+      }
+    });
+    return normalized.join("/");
+  }
+
+  // `base_url` comes from the base.html template for this theme.
+  var REL_BASE_URL = base_url;
+  var ABS_BASE_URL = normalizePath(window.location.pathname + "/" +
+                                   REL_BASE_URL);
+  var CURRENT_VERSION = ABS_BASE_URL.split("/").pop();
+
+  function makeSelect(options, selected) {
+    var select = document.createElement("select");
+
+    options.forEach(function(i) {
+      var option = new Option(i.text, i.value, undefined,
+                              i.value === selected);
+      select.add(option);
+    });
+
+    return select;
+  }
+
+  var xhr = new XMLHttpRequest();
+  xhr.open("GET", REL_BASE_URL + "/../versions.json");
+  xhr.onload = function() {
+    var versions = JSON.parse(this.responseText);
+
+    var realVersion = versions.find(function(i) {
+      return i.version === CURRENT_VERSION ||
+             i.aliases.includes(CURRENT_VERSION);
+    }).version;
+
+    var select = makeSelect(versions.map(function(i) {
+      return {text: i.title, value: i.version};
+    }), realVersion);
+    select.id = "version-selector";
+    select.addEventListener("change", function(event) {
+      window.location.href = REL_BASE_URL + "/../" + this.value;
+    });
+
+    var title = document.querySelector("div.wy-side-nav-search");
+    title.insertBefore(select, title.querySelector(".icon-home").nextSibling);
+  };
+  xhr.send();
+});

docs/system-overview.md

@@ -26,7 +26,7 @@ When the simulation is finished, the ROS node will disconnect from the AS's ROS
 During the competition, the teams will not be allowed to access their ASs.
 All remote access to the environments will be cut off completely.
 So every AS must be able to run multiple missions without human interference.
-To let the simulation know what is expected from it, the simulator will send mission control messages a few seconds before the event start.
+To let the simulation know what is expected from it, the simulator will send signal messages a few seconds before the event start.
 These messages contain information about the mission (trackdrive, autocross, etc).
 When the AS receives a mission message it can expect to receive sensor data shortly after.
 Since the lap timer for all events start whenever the car crosses the start-line, the ASs can take all the time they need to launch their relevant algorithms for the mission (within a reasonable time).
@@ -62,6 +62,10 @@ It gives a timeline of everything that happened to always go back afterwards and
 The logbook is stored on disk so that in the event of a whole system crash we will still have the logbook.
 It is also shown within the referee's web interface.
 
+You can run the simulation stack yourself perfectly fine without the operator.
+The operator is just a tool for officials to easely manage the competition.
+[Read more about how to run the simulation here.](how-to-simulate.md)
+
 ## The ROS Bridge
 The ROS bridge node connects to the simulated world inside Unreal Engine using AirSim (more on that later).
 On the one hand, it requests sensor data and passes it along on ROS topics to the current AS.
@@ -83,7 +87,6 @@ If the AS wants to store things (like track information), this is the time to wr
 In case of a successfull run the official will instruct the operator to stop the ROS bridge and the AS won't receive sensor data anymore.
 When the official presses the emergency brake, the connection between the ROS bridge is stopped immediately and the operator will send one last car setpoint to make the car come to a stop. 
 Thers is no 'stop' signal from the simulator to the AS.
-We advise AS to get ready for a new drive when no sensor data is received for 2 seconds.
 
 At this point only ROS is supported, at this moment there are no plans to support other technologies.
 

mkdocs.yml

@@ -1,6 +1,10 @@
 site_name: Formula Student Driverless Simulator
 theme: readthedocs
 site_description: A virtual world where Autonomous Systems from different Formula Student teams can compete in time-trial challenges
+repo_name: FS-Online/Formula-Student-Driverless-Simulator
+repo_url: https://github.com/FS-Online/Formula-Student-Driverless-Simulator
+edit_uri: 
+copyright: GPLv2
 
 nav:
   - "Home": "README.md"
@@ -21,4 +25,8 @@ nav:
     - "ROS Bridge": "ros-bridge.md"
     - "ROS Bridge statistics": "statistics.md"
     - "Joystick": "joystick.md"
-    - "Operator": "operator.md"
+    - "Operator": "operator.md"
+extra_css:
+  - css\version-select.css
+extra_javascript:
+  - js\version-select.js