From 083c0bad4fc99c006cbd111a08422bfb98a4b5a4 Mon Sep 17 00:00:00 2001
From: nsubiron <nsubiron@cvc.uab.es>
Date: Wed, 21 Mar 2018 18:16:56 +0100
Subject: [PATCH] Clean up documentation format

---
 Docs/benchmark.md                             |  66 ++++---
 Docs/cameras_and_sensors.md                   |  19 +-
 Docs/carla_headless.md                        | 112 ++++++-----
 Docs/carla_server.md                          |   9 +-
 Docs/carla_settings.md                        |  47 ++++-
 Docs/coding_standard.md                       |  27 ++-
 Docs/connecting_the_client.md                 |   5 +-
 ...erials.md => epic_automotive_materials.md} |  14 +-
 Docs/faq.md                                   |   2 +
 Docs/how_to_add_assets.md                     |   5 +-
 Docs/how_to_build_on_linux.md                 |  20 +-
 Docs/how_to_build_on_windows.md               |   3 +-
 Docs/how_to_run.md                            | 174 ------------------
 Docs/index.md                                 |  28 +--
 Docs/map_customization.md                     |  28 +--
 Docs/measurements.md                          |  13 +-
 mkdocs.yml                                    |  17 +-
 17 files changed, 248 insertions(+), 341 deletions(-)
 rename Docs/{how_to_add_automotive_materials.md => epic_automotive_materials.md} (78%)
 delete mode 100644 Docs/how_to_run.md

diff --git a/Docs/benchmark.md b/Docs/benchmark.md
index b42d6eafa..b1f4e29d5 100644
--- a/Docs/benchmark.md
+++ b/Docs/benchmark.md
@@ -1,5 +1,4 @@
-CARLA Benchmark
-===============
+<h1>CARLA Benchmark</h1>
 
 Running the Benchmark
 ---------------------
@@ -9,7 +8,6 @@ tests on a certain agent. We already provide the same benchmark used in the CoRL
 2017 paper. By running this benchmark you can compare the results of your agent
 to the results obtained by the agents show in the paper.
 
-
 Besides the requirements of the CARLA client, the benchmark package also needs
 the future package
 
@@ -30,37 +28,51 @@ Run the help command to see options available
     $ ./run_benchmark.py --help
 
 Benchmarking your Agent
----------------------
+-----------------------
+
 The benchmark works by calling three lines of code
 
-    corl = CoRL2017(city_name=args.city_name, name_to_save=args.log_name)
-    agent = Manual(args.city_name)
-    results = corl.benchmark_agent(agent, client)
+```python
+corl = CoRL2017(city_name=args.city_name, name_to_save=args.log_name)
+agent = Manual(args.city_name)
+results = corl.benchmark_agent(agent, client)
+```
 
-This is excerpt is executed in the [run_benchmark.py](https://github.com/carla-simulator/carla/blob/master/PythonClient/run_benchmark.py) example.
+This is excerpt is executed in the
+[run_benchmark.py](https://github.com/carla-simulator/carla/blob/master/PythonClient/run_benchmark.py)
+example.
 
-First a *benchmark* object is defined, for this case, a CoRL2017 benchmark. This is object is used to benchmark a certain Agent. <br>
-On the second line of our sample code, there is an object of a Manual class instanced. This class inherited an Agent base class
-that is used by the *benchmark* object.
-To be benchmarked, an Agent subclass must redefine the *run_step* function as it is done in the following excerpt:
+First a *benchmark* object is defined, for this case, a CoRL2017 benchmark. This
+is object is used to benchmark a certain Agent.
 
-    def run_step(self, measurements, sensor_data, target):
-        """
-        Function to run a control step in the CARLA vehicle.
-		:param measurements: object of the Measurements type
-		:param sensor_data: images list object
-		:param target: target position of Transform type
-	    :return: an object of the control type.
-	    """
-        control = VehicleControl()
-        control.throttle = 0.9
-        return control
-The function receives measurements from the world, sensor data and a target position. With this, the function must return a control to the car, *i.e.* steering value, throttle value, brake value, etc.
+On the second line of our sample code, there is an object of a Manual class
+instanced. This class inherited an Agent base class that is used by the
+*benchmark* object. To be benchmarked, an Agent subclass must redefine the
+*run_step* function as it is done in the following excerpt:
 
-The [measurements](measurements.md), [target](measurements.md), [sensor_data](cameras_and_sensors.md) and [control](measurements.md) types are described on the documentation.
+```python
+def run_step(self, measurements, sensor_data, target):
+    """
+    Function to run a control step in the CARLA vehicle.
+    :param measurements: object of the Measurements type
+    :param sensor_data: images list object
+    :param target: target position of Transform type
+    :return: an object of the control type.
+    """
+    control = VehicleControl()
+    control.throttle = 0.9
+    return control
+```
 
+The function receives measurements from the world, sensor data and a target
+position. With this, the function must return a control to the car, *i.e.*
+steering value, throttle value, brake value, etc.
 
+The [measurements](measurements.md), [target](measurements.md),
+[sensor_data](cameras_and_sensors.md) and [control](measurements.md) types are
+described on the documentation.
 
 Creating your Benchmark
----------------------
-Tutorial to be added
+-----------------------
+
+> TODO
diff --git a/Docs/cameras_and_sensors.md b/Docs/cameras_and_sensors.md
index 23496f7a7..310597f6a 100644
--- a/Docs/cameras_and_sensors.md
+++ b/Docs/cameras_and_sensors.md
@@ -1,5 +1,4 @@
-Cameras and sensors
-===================
+<h1>Cameras and sensors</h1>
 
 !!! important
     Since version 0.8.0 the positions of the sensors are specified in meters
@@ -59,7 +58,7 @@ in the Camera. We use the following post process effects:
 
 [postprolink]: https://docs.unrealengine.com/latest/INT/Engine/Rendering/PostProcessEffects/
 
-###### Python
+<h6>Python</h6>
 
 ```py
 camera = carla.sensor.Camera('MyCamera', PostProcessing='SceneFinal')
@@ -71,7 +70,7 @@ camera.set_rotation(pitch=0, yaw=0, roll=0)
 carla_settings.add_sensor(camera)
 ```
 
-###### CarlaSettings.ini
+<h6>CarlaSettings.ini</h6>
 
 ```ini
 [CARLA/Sensor/MyCamera]
@@ -120,7 +119,7 @@ The generated "depth map" images are usually converted to a logarithmic
 grayscale for display. A point cloud can also be extracted from depth images as
 seen in "PythonClient/point_cloud_example.py".
 
-###### Python
+<h6>Python</h6>
 
 ```py
 camera = carla.sensor.Camera('MyCamera', PostProcessing='Depth')
@@ -132,7 +131,7 @@ camera.set_rotation(pitch=0, yaw=0, roll=0)
 carla_settings.add_sensor(camera)
 ```
 
-###### CarlaSettings.ini
+<h6>CarlaSettings.ini</h6>
 
 ```ini
 [CARLA/Sensor/MyCamera]
@@ -190,7 +189,7 @@ _"Unreal/CarlaUE4/Content/Static/Pedestrians"_ folder it's tagged as pedestrian.
     and its corresponding filepath check inside `GetLabelByFolderName()`
     function in "Tagger.cpp".
 
-###### Python
+<h6>Python</h6>
 
 ```py
 camera = carla.sensor.Camera('MyCamera', PostProcessing='SemanticSegmentation')
@@ -202,7 +201,7 @@ camera.set_rotation(pitch=0, yaw=0, roll=0)
 carla_settings.add_sensor(camera)
 ```
 
-###### CarlaSettings.ini
+<h6>CarlaSettings.ini</h6>
 
 ```ini
 [CARLA/Sensor/MyCamera]
@@ -243,7 +242,7 @@ channels                   | uint32     | Number of channels (lasers) of the lid
 point_count_by_channel     | uint32     | Number of points per channel captured this frame.
 point_cloud                | PointCloud | Captured points this frame.
 
-###### Python
+<h6>Python</h6>
 
 ```py
 lidar = carla.sensor.Lidar('MyLidar')
@@ -260,7 +259,7 @@ lidar.set_rotation(pitch=0, yaw=0, roll=0)
 carla_settings.add_sensor(lidar)
 ```
 
-###### CarlaSettings.ini
+<h6>CarlaSettings.ini</h6>
 
 ```ini
 [CARLA/Sensor/MyLidar]
diff --git a/Docs/carla_headless.md b/Docs/carla_headless.md
index 095ab2bd7..2838c2a5c 100644
--- a/Docs/carla_headless.md
+++ b/Docs/carla_headless.md
@@ -1,89 +1,105 @@
-Running CARLA without Display and Selecting GPUs 
-------
+<h1>Running CARLA without Display and Selecting GPUs</h1>
 
+!!! note
+    See [#225](https://github.com/carla-simulator/carla/issues/225) for an
+    alternative method.
 
-This tutorial is designed for: 
-- Remote server users that have several nvidia  graphical cards and want to effectively use CARLA on all GPUs.
-- Desktop users who want to use the GPU that is not plugged on the screen for rendering CARLA.
+This tutorial is designed for
 
+  * Remote server users that have several nvidia  graphical cards and want to
+    effectively use CARLA on all GPUs.
+  * Desktop users who want to use the GPU that is not plugged on the screen for
+    rendering CARLA.
 
-On this tutorial you will learn.
-- How to configure your server to have nvidia working on rendering without a display attached.
--  How to use VNC + VGL to simulate a display connected to any GPU you have in your machine.
-- And Finally, how to run CARLA in this environment
+On this tutorial you will learn
+
+  * How to configure your server to have nvidia working on rendering without a
+    display attached.
+  * How to use VNC + VGL to simulate a display connected to any GPU you have in
+    your machine.
+  * And Finally, how to run CARLA in this environment
 
 This tutorial was tested in Ubuntu 16.04 and using NVIDIA 384.11 drivers.
-## Preliminaries 
 
-A few things need to be working in your server before.
- Latest NVIDIA Drivers, OpenGL,  VirtualGL(VGL), TurboVNC 2.11, ,
-#### NVIDIA Drivers
-Download and install NVIDIA-drivers with typical tutorials
-http://www.nvidia.es/Download/index.aspx
-#### OpenGL
-Openg GL is necessary for Virtual GL. Normally OpenGL
-can be installed through apt.
+## Preliminaries
+
+A few things need to be working in your server before. Latest NVIDIA Drivers,
+OpenGL, VirtualGL(VGL), TurboVNC 2.11.
+
+<h4>NVIDIA Drivers</h4>
+
+Download and install [NVIDIA-drivers][nvidialink] with typical tutorials.
+
+[nvidialink]: http://www.nvidia.es/Download/index.aspx
+
+<h4>OpenGL</h4>
+
+Openg GL is necessary for Virtual GL. Normally OpenGL can be installed through
+apt.
 
     sudo apt-get install freeglut3-dev mesa-utils
-####  VGL
-Follow this tutorial and install vgl: <br>
+
+<h4>VGL</h4>
+
+Follow this tutorial and install vgl:
 [Installing VGL](https://virtualgl.org/vgldoc/2_2_1/#hd004001)
 
-#### TurboVNC
-Follow the tutorial below to install TurboVNC 2.11:<br>
+<h4>TurboVNC</h4>
+
+Follow the tutorial below to install TurboVNC 2.11:
 [Installing TurboVNC](https://cdn.rawgit.com/TurboVNC/turbovnc/2.1.1/doc/index.html#hd005001)
 
-WARNING: Take care on which VNC you install as it may not be compatible with Unreal. The one above was the only one that worked for me. 
-#### Extra Packages
+WARNING: Take care on which VNC you install as it may not be compatible with
+Unreal. The one above was the only one that worked for me.
+
+<h4>Extra Packages</h4>
+
 These extra packages were necessary to make unreal to work.
 
     sudo apt install x11-xserver-utils libxrandr-dev
 
+<h4>Configure your X</h4>
 
-
-
-#### Configure your X
-
-You must generate a X compatible with your nvdia and compatible to run without display. For that, the following command worked:
+You must generate a X compatible with your nvdia and compatible to run without
+display. For that, the following command worked:
 
     sudo nvidia-xconfig -a --use-display-device=None --virtual=1280x1024
 
-
-
 ## Emulating The Virtual Display
 
-
-Run your own Xorg. Here I use number 7, but it could be labeled with any free number.
+Run your own Xorg. Here I use number 7, but it could be labeled with any free
+number
 
     sudo nohup Xorg :7 &
 
-Run an auxiliary remote VNC-Xserver. This will create a
-virtual display  "8".
+Run an auxiliary remote VNC-Xserver. This will create a virtual display "8".
 
     /opt/TurboVNC/bin/vncserver :8
 
-If everything is working fine the following command
-should run smoothly.
+If everything is working fine the following command should run smoothly.
 
     DISPLAY=:8 vglrun -d :7.0 glxinfo
-Note. This will run glxinfo on Xserver 7, device 0. This means you are selecting the GPU 0 on your machine. To run on other GPU, such as GPU 1 run:
+
+Note. This will run glxinfo on Xserver 7, device 0. This means you are selecting
+the GPU 0 on your machine. To run on other GPU, such as GPU 1 run:
 
     DISPLAY=:8 vglrun -d :7.1 glxinfo
 
-#### Extra
+<h4>Extra</h4>
 
-If you want disable the need of sudo when creating the  'nohup Xorg'
-go to the '/etc/X11/Xwrapper.config'  file and change 'allowed_users=console' to 'allowed_users=anybody'
+If you want disable the need of sudo when creating the 'nohup Xorg' go to the
+'/etc/X11/Xwrapper.config' file and change 'allowed_users=console' to
+'allowed_users=anybody'
 
-It may be needed to stop all Xorg servers before running nohup Xorg.
-The command for that could change depending on your system. Generally for Ubuntu 16.04
-you should use:
+It may be needed to stop all Xorg servers before running nohup Xorg. The command
+for that could change depending on your system. Generally for Ubuntu 16.04 you
+should use:
 
     sudo service lightdm stop
 
+## Running CARLA
 
-## Running CARLA 
+Now, finally, to run CARLA on a certain gpu_number placed in a certain
+$CARLA_PATH, run.
 
-Now, finally, to run CARLA on a certain gpu_number placed in a certain $CARLA_PATH, run.
-
-    DISPLAY=:8 vglrun -d :7.<gpu_number> $CARLA_PATH/CarlaUE4/Binaries/Linux/CarlaUE4 
+    DISPLAY=:8 vglrun -d :7.<gpu_number> $CARLA_PATH/CarlaUE4/Binaries/Linux/CarlaUE4
diff --git a/Docs/carla_server.md b/Docs/carla_server.md
index ebbd38c8f..5d2d332e1 100644
--- a/Docs/carla_server.md
+++ b/Docs/carla_server.md
@@ -1,5 +1,4 @@
-CARLA Server
-============
+<h1>CARLA Server</h1>
 
 Build
 -----
@@ -28,7 +27,7 @@ Three consecutive ports are used,
 each of these ports has an associated thread that sends/reads data
 asynchronuosly.
 
-###### World thread
+<h4>World thread</h4>
 
 Server reads one, writes one. Always protobuf messages.
 
@@ -38,7 +37,7 @@ Server reads one, writes one. Always protobuf messages.
     [server] EpisodeReady
     ...repeat...
 
-###### Measurements thread
+<h4>Measurements thread</h4>
 
 Server only writes, first measurements message then the bulk of raw images.
 
@@ -63,7 +62,7 @@ The measurements message is explained in detail [here](measurements.md).
 
 [fcolorlink]: https://docs.unrealengine.com/latest/INT/API/Runtime/Core/Math/FColor/index.html "FColor API Documentation"
 
-###### Control thread
+<h4>Control thread</h4>
 
 Server only reads, client sends Control message every frame.
 
diff --git a/Docs/carla_settings.md b/Docs/carla_settings.md
index 4029c5d42..25c270f5c 100644
--- a/Docs/carla_settings.md
+++ b/Docs/carla_settings.md
@@ -1,5 +1,9 @@
-CARLA Settings
-==============
+<h1>CARLA Settings</h1>
+
+> _This document is a work in progress and might be incomplete._
+
+CarlaSettings.ini
+-----------------
 
 CARLA reads its settings from a "CarlaSettings.ini" file. This file controls
 most aspects of the simulation, and it is loaded every time a new episode is
@@ -16,3 +20,42 @@ hierarchy overriding earlier values.
 Take a look at the [CARLA Settings example][settingslink].
 
 [settingslink]: https://github.com/carla-simulator/carla/blob/master/Docs/Example.CarlaSettings.ini
+
+Weather presets
+---------------
+
+The weather and lighting conditions can be chosen from a set of predefined
+settings. To select one, set the `WeatherId` key in CarlaSettings.ini. The
+following presets are available
+
+  * 0 - Default
+  * 1 - ClearNoon
+  * 2 - CloudyNoon
+  * 3 - WetNoon
+  * 4 - WetCloudyNoon
+  * 5 - MidRainyNoon
+  * 6 - HardRainNoon
+  * 7 - SoftRainNoon
+  * 8 - ClearSunset
+  * 9 - CloudySunset
+  * 10 - WetSunset
+  * 11 - WetCloudySunset
+  * 12 - MidRainSunset
+  * 13 - HardRainSunset
+  * 14 - SoftRainSunset
+
+E.g., to choose the weather to be hard-rain at noon, add to CarlaSettings.ini
+
+```
+[CARLA/LevelSettings]
+WeatherId=6
+```
+
+Simulator command-line options
+------------------------------
+
+  * `-carla-server` Launches CARLA as server, the execution hangs until a client connects.
+  * `-carla-settings="Path/To/CarlaSettings.ini"` Load settings from the given INI file. See Example.CarlaSettings.ini.
+  * `-carla-world-port=N` Listen for client connections at port N, agent ports are set to N+1 and N+2 respectively. Activates server.
+  * `-carla-no-hud` Do not display the HUD by default.
+  * `-carla-no-networking` Disable networking. Overrides `-carla-server` if present.
diff --git a/Docs/coding_standard.md b/Docs/coding_standard.md
index f03eae186..157b81570 100644
--- a/Docs/coding_standard.md
+++ b/Docs/coding_standard.md
@@ -1,5 +1,4 @@
-Coding standard
-===============
+<h1>Coding standard</h1>
 
 > _This document is a work in progress and might be incomplete._
 
@@ -8,18 +7,30 @@ General
 
   * Use spaces, not tabs.
   * Avoid adding trailing whitespace as it creates noise in the diffs.
-  * Comments should not exceed 80 columns, code may exceed this limit a bit in rare occasions if it results in clearer code.
+  * Comments should not exceed 80 columns, code may exceed this limit a bit in
+    rare occasions if it results in clearer code.
 
 Python
 ------
 
   * All code must be compatible with Python 2.7, 3.5, and 3.6.
-  * [Pylint](https://www.pylint.org/) should not give any error or warning (few exceptions apply with external classes like `numpy`, see our `.pylintrc`).
-  * Python code follows [PEP8 style guide](https://www.python.org/dev/peps/pep-0008/) (use `autopep8` whenever possible).
+  * [Pylint][pylintlink] should not give any error or warning (few exceptions
+    apply with external classes like `numpy`, see our `.pylintrc`).
+  * Python code follows [PEP8 style guide][pep8link] (use `autopep8` whenever
+    possible).
+
+[pylintlink]: https://www.pylint.org/
+[pep8link]: https://www.python.org/dev/peps/pep-0008/
 
 C++
 ---
 
-  * Compilation should not give any error or warning (`clang++ -Wall -Wextra -std=C++14`).
-  * Unreal C++ code (CarlaUE4 and Carla plugin) follow the [Unreal Engine's Coding Standard](https://docs.unrealengine.com/latest/INT/Programming/Development/CodingStandard/) with the exception of using spaces instead of tabs.
-  * CarlaServer uses [Google's style guide](https://google.github.io/styleguide/cppguide.html).
+  * Compilation should not give any error or warning
+    (`clang++ -Wall -Wextra -std=C++14`).
+  * Unreal C++ code (CarlaUE4 and Carla plugin) follow the
+    [Unreal Engine's Coding Standard][ue4link] with the exception of using
+    spaces instead of tabs.
+  * CarlaServer uses [Google's style guide][googlelink].
+
+[ue4link]: https://docs.unrealengine.com/latest/INT/Programming/Development/CodingStandard/
+[googlelink]: https://google.github.io/styleguide/cppguide.html
diff --git a/Docs/connecting_the_client.md b/Docs/connecting_the_client.md
index 286727156..e436d9bb7 100644
--- a/Docs/connecting_the_client.md
+++ b/Docs/connecting_the_client.md
@@ -72,8 +72,9 @@ the Python script.
 
 !!! important
     Before you start running your own experiments, it is important to know the
-    details for running the simulation at [fixed time-step](fixed_time_step.md)
-    for achieving maximum speed and repeatability.
+    details for running the simulator at **fixed time-step** for achieving
+    maximum speed and repeatability. We will cover this in the next item
+    [Configuring the simulation](configuring_the_simulation.md).
 
 <h4>Saving images to disk</h4>
 
diff --git a/Docs/how_to_add_automotive_materials.md b/Docs/epic_automotive_materials.md
similarity index 78%
rename from Docs/how_to_add_automotive_materials.md
rename to Docs/epic_automotive_materials.md
index a092c7bd3..7bd48368c 100644
--- a/Docs/how_to_add_automotive_materials.md
+++ b/Docs/epic_automotive_materials.md
@@ -1,10 +1,12 @@
-How to add the automotive materials
-===================================
+<h1>How to link Epic's Automotive Materials</h1>
 
-CARLA uses Epic Game's Automotive Materials package for a realistic car paint
-look. Due to license restrictions we are not allowed to redistribute this
-package. In this document we explain how to download and link these materials to
-our vehicles.
+!!! important
+    Since version 0.8.0 CARLA does not use Epic's _Automotive Materials_ by
+    default. However, you can still enable them if you compile from source.
+
+Epic Game's provides a set of realistic _Automotive Materials_ free to use. In
+this document we explain how to download and link these materials to our
+vehicles for a more realistic car paint.
 
 Download from Marketplace
 -------------------------
diff --git a/Docs/faq.md b/Docs/faq.md
index 9ba884469..580115e1a 100644
--- a/Docs/faq.md
+++ b/Docs/faq.md
@@ -1,3 +1,5 @@
+<h1>CARLA F.A.Q.</h1>
+
 <!-- ======================================================================= -->
 <details>
   <summary><h5 style="display:inline">
diff --git a/Docs/how_to_add_assets.md b/Docs/how_to_add_assets.md
index 3a32624c0..f60962373 100644
--- a/Docs/how_to_add_assets.md
+++ b/Docs/how_to_add_assets.md
@@ -1,5 +1,6 @@
-How to add assets
-=================
+<h1>How to add assets</h1>
+
+> _This document is a work in progress and might be incomplete._
 
 Adding a vehicle
 ----------------
diff --git a/Docs/how_to_build_on_linux.md b/Docs/how_to_build_on_linux.md
index c1023e9a6..2e61ddada 100644
--- a/Docs/how_to_build_on_linux.md
+++ b/Docs/how_to_build_on_linux.md
@@ -1,13 +1,11 @@
-How to build CARLA on Linux
-===========================
+<h1>How to build CARLA on Linux</h1>
 
 !!! note
     CARLA requires Ubuntu 16.04 or later.
 
 Install the build tools and dependencies
 
-    $ sudo apt-get install build-essential clang-3.9 git cmake ninja-build python3-pip python3-requests python-dev tzdata sed curl wget unzip autoconf libtool
-    $ sudo pip3 install protobuf
+    $ sudo apt-get install build-essential clang-3.9 git cmake ninja-build python3-requests python-dev tzdata sed curl wget unzip autoconf libtool
 
 To avoid compatibility issues between Unreal Engine and the CARLA dependencies,
 the best configuration is to compile everything with the same compiler version
@@ -47,16 +45,6 @@ takes a while
 
 Once it's done it should print "Success" if everything went well.
 
-Download Epic Games' Automotive Materials package and install it under
-"Unreal/CarlaUE4/Content/AutomotiveMaterials".
-[How to download automotive materials](how_to_add_automotive_materials.md).
-
-!!! note
-    Due to license restrictions, pedestrians are not include in the CARLA open
-    source project (only in the compiled binaries). Some warnings may appear
-    when starting the project related to this. We are working to find a
-    solution.
-
 To build CARLA, use the rebuild script. This script deletes all intermediate
 files, rebuilds whole CARLA, and launches the editor. Use it too for making a
 clean rebuild of CARLA
@@ -66,10 +54,6 @@ clean rebuild of CARLA
 It looks at the environment variable `UE4_ROOT` to find the right version of
 Unreal Engine. You can also add this variable to your "~/.bashrc" or similar.
 
-Once the project is opened, it is required to manually link Epic's Automotive
-Materials to our vehicles.
-[How to link automotive materials](how_to_add_automotive_materials.md).
-
 Later, if you need to compile some changes without doing a full rebuild, you can
 use the Makefile generated in the Unreal project folder
 
diff --git a/Docs/how_to_build_on_windows.md b/Docs/how_to_build_on_windows.md
index 4fe12d57e..27b95f65f 100644
--- a/Docs/how_to_build_on_windows.md
+++ b/Docs/how_to_build_on_windows.md
@@ -1,5 +1,4 @@
-How to build CARLA on Windows
-=============================
+<h1>How to build CARLA on Windows</h1>
 
 !!! important
     We are working on an automated build system for Windows, you can follow
diff --git a/Docs/how_to_run.md b/Docs/how_to_run.md
deleted file mode 100644
index 613d44b5a..000000000
--- a/Docs/how_to_run.md
+++ /dev/null
@@ -1,174 +0,0 @@
-CARLA Simulator
-===============
-
-!!! note
-    CARLA requires Ubuntu 16.04 or later.
-
-Welcome to CARLA simulator.
-
-This file contains the instructions to run the CARLA simulator binaries on
-Linux.
-
-[Get the latest release here.][releaselink]
-
-For building CARLA from source, please check out the
-[CARLA Documentation][docslink].
-
-CARLA can be run directly by running the "CarlaUE4.sh" script provided in the
-release package.
-
-There are currently two scenarios available, the desired scenario can be chosen
-from the command-line
-
-    $ ./CarlaUE4.sh /Game/Maps/Town01
-
-or
-
-    $ ./CarlaUE4.sh /Game/Maps/Town02
-
-To run CARLA as server, see ["Running the server"](#running-the-server) below.
-
-[releaselink]: https://github.com/carla-simulator/carla/releases/latest
-[docslink]: http://carla.readthedocs.io
-
-Running the Python client
--------------------------
-
-The "carla" Python module provides a basic API for communicating with the CARLA
-server. In the "PythonClient" folder we provide a couple of examples on how to
-use this API. We recommend Python 3, but they are also compatible with Python 2.
-
-Install the dependencies with
-
-    $ pip install -r PythonClient/requirements.txt
-
-The script "PythonClient/client_example.py" provides basic functionality for
-controlling the vehicle and saving images to disk. Run the help command to see
-options available
-
-    $ ./client_example.py --help
-
-The script "PythonClient/manual_control.py" launches a PyGame window with
-several views and allows to control the vehicle using the WASD keys.
-
-    $ ./manual_control.py --help
-
-Running the server
-------------------
-
-The server can be started by running the "CarlaUE4.sh" script with some extra
-arguments. When run in server mode (controlled by the CARLA client), it is
-highly recommended to run it at fixed time-step
-
-    $ ./CarlaUE4.sh /Game/Maps/Town01 -carla-server -benchmark -fps=15
-
-The arguments `-benchmark -fps=15` make the engine run at a fixed time-step of
-1/15 seconds. In this mode, game-time decouples from real-time and the
-simulation runs as fast as possible.
-
-To run the game on the second town, just change the command to select the
-"Town02" map
-
-    $ ./CarlaUE4.sh /Game/Maps/Town02 -carla-server -benchmark -fps=15
-
-When run as server, it is sometimes useful to run the game in a smaller window,
-this can be chosen with
-
-    $ ./CarlaUE4.sh /Game/Maps/Town01 -carla-server -benchmark -fps=15 -windowed -ResX=800 -ResY=600
-
-#### CARLA specific command-line options
-
-  * `-carla-server` Launches CARLA as server, the execution hangs until a client connects.
-  * `-carla-settings="Path/To/CarlaSettings.ini"` Load settings from the given INI file. See Example.CarlaSettings.ini.
-  * `-carla-world-port=N` Listen for client connections at port N, agent ports are set to N+1 and N+2 respectively. Activates server.
-  * `-carla-no-hud` Do not display the HUD by default.
-  * `-carla-no-networking` Disable networking. Overrides `-carla-server` if present.
-
-#### Running CARLA off-screen
-
-CARLA can be run in a display-less computer without any further configuration.
-However, CARLA will render to the default GPU. This can be inconvenient on
-multi-GPU setups.
-
-Selecting the GPU can be achieved with VirtualGL and TurboVNC.
-
-  1. Install X-server.
-  2. Create a xorg.conf with `nvidia-xconfig -a --use-display-device=none` (first back up existing one if necessary).
-  3. Kill all running Xorg instances (`sudo service lightdm stop && sudo killall -9 Xorg`).
-  4. Check that X works `sudo Xorg :0` (it might be necessary to update nvidia drivers), then kill it.
-  5. Install [VirtualGL](https://sourceforge.net/projects/virtualgl/files/2.5.2/) and [TurboVNC](https://sourceforge.net/projects/turbovnc/files/2.1.1/) from deb packages (`sudo dpkg -i XXX.deb`).
-  6. Start CARLA.
-
-#### In-game controls
-
-The following key bindings are available during game play at the server window.
-Note that vehicle controls are only available when networking is disabled.
-
-    W            : throttle
-    S            : brake
-    AD           : steer
-    Q            : toggle reverse
-    Space        : hand-brake
-
-    P            : toggle autopilot
-
-    Arrow keys   : move camera
-    PgUp PgDn    : zoom in and out
-    mouse wheel  : zoom in and out
-    Tab          : toggle on-board camera
-
-    R            : restart level
-    G            : toggle HUD
-    C            : change weather/lighting
-
-    Enter        : jump
-    F            : use the force
-
-    F11          : toggle fullscreen
-    Alt+F4       : quit
-
-Settings
---------
-
-CARLA reads its settings from a "CarlaSettings.ini" file. This file controls
-most aspects of the simulator, and it is loaded every time a new episode is
-started (every time the level is loaded).
-
-Settings are loaded following the next hierarchy, with values later in the
-hierarchy overriding earlier values.
-
-  1. `{ProjectFolder}/Config/CarlaSettings.ini`.
-  2. File provided by command-line argument `-carla-settings="Path/To/CarlaSettings.ini"`.
-  3. Other command-line arguments as `-carla-server` or `-world-port`.
-  4. Settings file sent by the client on every new episode.
-
-Take a look at the Example.CarlaSettings.ini file for further details.
-
-#### Weather presets
-
-The weather and lighting conditions can be chosen from a set of predefined
-settings. To select one, set the `WeatherId` key in CarlaSettings.ini. The
-following presets are available
-
-  * 0 - Default
-  * 1 - ClearNoon
-  * 2 - CloudyNoon
-  * 3 - WetNoon
-  * 4 - WetCloudyNoon
-  * 5 - MidRainyNoon
-  * 6 - HardRainNoon
-  * 7 - SoftRainNoon
-  * 8 - ClearSunset
-  * 9 - CloudySunset
-  * 10 - WetSunset
-  * 11 - WetCloudySunset
-  * 12 - MidRainSunset
-  * 13 - HardRainSunset
-  * 14 - SoftRainSunset
-
-E.g., to choose the weather to be hard-rain at noon, add to CarlaSettings.ini
-
-```
-[CARLA/LevelSettings]
-WeatherId=6
-```
diff --git a/Docs/index.md b/Docs/index.md
index 3a4224a5f..f577aa37f 100644
--- a/Docs/index.md
+++ b/Docs/index.md
@@ -1,29 +1,35 @@
-CARLA Documentation
-===================
+<h1>CARLA Documentation</h1>
 
-#### Using CARLA
+<h3>Quick start</h3>
 
-  * [How to run CARLA server and client](how_to_run.md)
-  * [CARLA settings](carla_settings.md)
+  * [Getting started](getting_started.md)
+  * [Running the simulator](running_simulator_standalone.md)
+  * [Connecting a Python client](connecting_the_client.md)
+  * [Configuring the simulation](configuring_the_simulation.md)
   * [Measurements](measurements.md)
   * [Cameras and sensors](cameras_and_sensors.md)
-  * [CARLA without Display and Selecting GPUs](carla_headless.md)
-  * [Benchmark](benchmark.md)
   * [F.A.Q.](faq.md)
 
-#### Building from source
+<h3>Building from source</h3>
 
   * [How to build on Linux](how_to_build_on_linux.md)
   * [How to build on Windows](how_to_build_on_windows.md)
-  * [How to add Automotive Materials](how_to_add_automotive_materials.md)
 
-#### Contributing
+<h3>Advanced topics</h3>
+
+  * [CARLA settings](carla_settings.md)
+  * [Simulator keyboard input](simulator_keyboard_input.md)
+  * [Benchmark](benchmark.md)
+  * [Running without display and selecting GPUs](carla_headless.md)
+  * [How to link Epic's Automotive Materials](epic_automotive_materials.md)
+
+<h3>Contributing</h3>
 
   * [Contribution guidelines](CONTRIBUTING.md)
   * [Coding standard](coding_standard.md)
   * [Code of conduct](CODE_OF_CONDUCT.md)
 
-#### Development
+<h3>Development</h3>
 
   * [Map customization](map_customization.md)
   * [How to add assets](how_to_add_assets.md)
diff --git a/Docs/map_customization.md b/Docs/map_customization.md
index ce029721f..c396d4fcb 100644
--- a/Docs/map_customization.md
+++ b/Docs/map_customization.md
@@ -1,6 +1,9 @@
-# Map customization
+<h1>Map customization</h1>
 
-## Creating a new map
+> _This document is a work in progress and might be incomplete._
+
+Creating a new map
+------------------
 
 !!! Bug
     Creating a map from scratch with the Carla tools causes a crash with
@@ -8,11 +11,11 @@
     this guide will suggest duplicating an existing level instead of creating
     one from scratch.
 
-### Requirements
+<h4>Requirements</h4>
 
  - Checkout and build Carla from source on [Linux](how_to_build_on_linux.md) or [Windows](how_to_build_on_windows.md)
 
-### Creating
+<h4>Creating</h4>
 
 - Duplicate an existing map
 - Remove everything you don't need from the map
@@ -34,11 +37,8 @@
 Every street at a crossing should have its own turn at green without the other streets having green.
 - Then you can populate the world with landscape and buildings.
 
-## Blueprint Assets
-
-This are the specific blueprint assets created to help building the environment.
-
-## MultipleFloorBuilding:
+MultipleFloorBuilding
+---------------------
 
 The purpose of this blueprint is to make repeating and varying tall buildings a
 bit easier. Provided a Base, a MiddleFloor and a roof; this blueprint repeats
@@ -60,12 +60,13 @@ This blueprint is controlled by this 6 specific Parameters:
 All of This parameters can be modified once this blueprint is placed in the
 world.
 
-## SplinemeshRepeater:
+SplinemeshRepeater
+------------------
 
 !!! Bug
     See [#35 SplineMeshRepeater loses its collider mesh](https://github.com/carla-simulator/carla/issues/35)
 
-### Standard use:
+<h4>Standard use:</h4>
 
 SplineMeshRepeater "Content/Blueprints/SplineMeshRepeater" is a tool included in
 the Carla Project to help building urban environments; It repeats and aligns a
@@ -91,7 +92,7 @@ the lower point possible with the rest of the mesh pointing positive (Preferably
 by the X axis)
 
 
-### Specific Walls (Dynamic material)
+<h4>Specific Walls (Dynamic material)</h4>
 
 In the project folder "Content/Static/Walls" are included some specific assets
 to be used with this SplineMeshRepeater with a series of special
@@ -118,7 +119,8 @@ The rest of the parameters are the mask the textures and the color corrections
 that won't be modified in this instance but in the blueprint that will be
 launched into the world.
 
-## Weather
+Weather
+-------
 
 This is the actor in charge of modifying all the lighting, environmental actors
 an anything that affects the impression of the climate. It runs automatically
diff --git a/Docs/measurements.md b/Docs/measurements.md
index bff877e03..88d6b86cd 100644
--- a/Docs/measurements.md
+++ b/Docs/measurements.md
@@ -1,5 +1,4 @@
-Measurements
-============
+<h1>Measurements</h1>
 
 !!! important
     Since version 0.8.0 the measurements received by the client are in SI
@@ -40,7 +39,7 @@ intersection_otherlane     | float     |        | Percentage of the car invading
 intersection_offroad       | float     |        | Percentage of the car off-road.
 autopilot_control          | Control   |        | Vehicle's autopilot control that would apply this frame.
 
-###### Transform
+<h4>Transform</h4>
 
 The transform contains the location and rotation of the player.
 
@@ -50,7 +49,7 @@ location                   | Vector3D   | m       | World location.
 orientation *[deprecated]* | Vector3D   |         | Orientation in Cartesian coordinates.
 rotation                   | Rotation3D | degrees | Pitch, roll, and yaw.
 
-###### Collision
+<h4>Collision</h4>
 
 Collision variables keep an accumulation of all the collisions occurred during
 this episode. Every collision contributes proportionally to the intensity of the
@@ -65,7 +64,7 @@ objects are classified based on their tag (same as for semantic segmentation).
 Collisions are not annotated if the vehicle is not moving (<1km/h) to avoid
 annotating undesired collision due to mistakes in the AI of non-player agents.
 
-###### Lane/off-road intersection
+<h4>Lane/off-road intersection</h4>
 
 The lane intersection measures the percentage of the vehicle invading the
 opposite lane. The off-road intersection measures the percentage of the vehicle
@@ -76,7 +75,7 @@ rectangle) against the map image of the city. These images are generated in the
 editor and serialized for runtime use. You can find them too in the release
 package under the folder "RoadMaps".
 
-###### Autopilot control
+<h4>Autopilot control</h4>
 
 The `autopilot_control` measurement contains the control values that the in-game
 autopilot system would apply as if it were controlling the vehicle.
@@ -135,7 +134,7 @@ belongs to one of the following classes
 (*) At this point every pedestrian is assumed to have the same bounding-box
 size.
 
-###### Transform and bounding box
+<h4>Transform and bounding box</h4>
 
 The transform defines the location and orientation of the agent. The bounding
 box is centered at the agent's location. The box extent gives the radii
diff --git a/mkdocs.yml b/mkdocs.yml
index 9a9b6db11..68d3b5cd1 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -5,18 +5,23 @@ theme: readthedocs
 
 pages:
 - Home: 'index.md'
-- Using CARLA:
-  - 'How to run CARLA server and client': 'how_to_run.md'
-  - 'CARLA Settings': 'carla_settings.md'
+- Quick start:
+  - 'Getting started': 'getting_started.md'
+  - 'Running the simulator': 'running_simulator_standalone.md'
+  - 'Connecting a Python client': 'connecting_the_client.md'
+  - 'Configuring the simulation': 'configuring_the_simulation.md'
   - 'Measurements': 'measurements.md'
   - 'Cameras and sensors': 'cameras_and_sensors.md'
-  - 'CARLA without Display and Selecting GPUs': 'carla_headless.md'
-  - 'Benchmark': 'benchmark.md'
   - 'F.A.Q.': 'faq.md'
 - Building from source:
   - 'How to build on Linux': 'how_to_build_on_linux.md'
   - 'How to build on Windows': 'how_to_build_on_windows.md'
-  - 'How to add Automotive Materials': 'how_to_add_automotive_materials.md'
+- Advanced topics:
+  - 'CARLA Settings': 'carla_settings.md'
+  - 'Simulator keyboard input': 'simulator_keyboard_input.md'
+  - 'Benchmark': 'benchmark.md'
+  - 'Running without display and selecting GPUs': 'carla_headless.md'
+  - "How to link Epic's Automotive Materials": 'epic_automotive_materials.md'
 - Contributing:
   - 'Contribution guidelines': 'CONTRIBUTING.md'
   - 'Coding standard': 'coding_standard.md'