#95 markdown instead of rst #80

AUTHORS.md

+Credits
+=======
+
+Development
+-----------
+
+* Christian Baumberger <christian.baumberger@sbb.ch>
+* Christian Eichenberger <christian.markus.eichenberger@sbb.ch>
+* Adrian Egli <adrian.egli@sbb.ch>
+* Mattias Ljungström
+* Sharada Mohanty <mohanty@aicrowd.com>
+* Guillaume Mollard <guillaume.mollard2@gmail.com>
+* Erik Nygren <erik.nygren@sbb.ch>
+* Giacomo Spigler <giacomo.spigler@gmail.com>
+* Jeremy Watson
+
+
+Acknowledgements
+----------------
+* Vaibhav Agrawal <theinfamouswayne@gmail.com>
+* Anurag Ghosh
+
+
+Contributors
+------------
+
+None yet. Why not be the first?

AUTHORS.rst

-=======
-Credits
-=======
-
-Development
-----------------
-
-* S.P. Mohanty <mohanty@aicrowd.com>
-
-* G Spigler <giacomo.spigler@gmail.com>
-
-* A Egli <adrian.egli@sbb.ch>
-
-* E Nygren <erik.nygren@sbb.ch>
-
-* Ch. Eichenberger <christian.markus.eichenberger@sbb.ch>
-
-* Mattias Ljungström
-
-Contributors
-------------
-
-None yet. Why not be the first?

CONTRIBUTING.rst

@@ -135,3 +135,70 @@ $ git push
 $ git push --tags
 
 TODO: Travis will then deploy to PyPI if tests pass. (To be configured properly by Mohanty)
+
+
+Local Evaluation
+----------------
+
+This document explains you how to locally evaluate your submissions before making
+an official submission to the competition.
+
+Requirements
+~~~~~~~~~~~~
+
+* **flatland-rl** : We expect that you have `flatland-rl` installed by following the instructions in  [README.md](README.md).
+
+* **redis** : Additionally you will also need to have  `redis installed <https://redis.io/topics/quickstart>`_ and **should have it running in the background.**
+
+Test Data
+~~~~~~~~~
+
+* **test env data** : You can `download and untar the test-env-data <https://www.aicrowd.com/challenges/flatland-challenge/dataset_files>`, at a location of your choice, lets say `/path/to/test-env-data/`. After untarring the folder, the folder structure should look something like:
+
+
+.. code-block:: console
+
+    .
+    └── test-env-data
+        ├── Test_0
+        │   ├── Level_0.pkl
+        │   └── Level_1.pkl
+        ├── Test_1
+        │   ├── Level_0.pkl
+        │   └── Level_1.pkl
+        ├..................
+        ├..................
+        ├── Test_8
+        │   ├── Level_0.pkl
+        │   └── Level_1.pkl
+        └── Test_9
+            ├── Level_0.pkl
+            └── Level_1.pkl
+
+Evaluation Service
+~~~~~~~~~~~~~~~~~~
+
+* **start evaluation service** : Then you can start the evaluator by running :
+
+.. code-block:: console
+
+    flatland-evaluator --tests /path/to/test-env-data/
+
+RemoteClient
+~~~~~~~~~~~~
+
+* **run client** : Some `sample submission code can be found in the starter-kit <https://github.com/AIcrowd/flatland-challenge-starter-kit/>`_, but before you can run your code locally using `FlatlandRemoteClient`, you will have to set the `AICROWD_TESTS_FOLDER` environment variable to the location where you previous untarred the folder with `the test-env-data`:
+
+
+.. code-block:: console
+
+    export AICROWD_TESTS_FOLDER="/path/to/test-env-data/"
+
+    # or on Windows :
+    #
+    # set AICROWD_TESTS_FOLDER "\path\to\test-env-data\"
+
+    # and then finally run your code
+    python run.py
+
+

docs/about_flatland.rst → README.md

-About Flatland
-==============
+Flatland
+========
 
-.. image:: https://i.imgur.com/rKGEmsk.gif
-  :align: center
+![Test Running](https://gitlab.aicrowd.com/flatland/flatland/badges/master/pipeline.svg)![Test Coverage](https://gitlab.aicrowd.com/flatland/flatland/badges/master/coverage.svg "asdff")
 
 
+![Flatland](https://i.imgur.com/0rnbSLY.gif)
+
+## About Flatland
 
 Flatland is a toolkit for developing and comparing multi agent reinforcement learning algorithms on grids.
 The base environment is a two-dimensional grid in which many agents can be placed. Each agent must solve one or more tasks in the grid world.
@@ -35,10 +37,127 @@ This library was developed by `SBB <https://www.sbb.ch/en/>`_ , `AIcrowd <https:
 This library was developed specifically for the `Flatland Challenge <https://www.aicrowd.com/challenges/flatland-challenge>`_ in which we strongly encourage you to take part in. 
 
 
-.. image:: https://i.imgur.com/pucB84T.gif
-  :align: center
-  :width: 600px
+![Flatland](https://i.imgur.com/pucB84T.gif)
+![Flatland](https://i.imgur.com/xgWGRse.gif)
+
+**NOTE This document is best viewed in the official documentation site at** `Flatland-RL Docs <http://flatland-rl-docs.s3-website.eu-central-1.amazonaws.com/>`_
+
+
+## Installation
+### Installation Prerequistes
+
+* Install [Anaconda](https://www.anaconda.com/distribution/) by following the instructions [here](https://www.anaconda.com/distribution/).
+* Create a new conda environment:
+
+```console
+$ conda create python=3.6 --name flatland-rl
+$ conda activate flatland-rl
+```
+
+* Install the necessary dependencies
+
+```console
+$ conda install -c conda-forge cairosvg pycairo
+$ conda install -c anaconda tk  
+```
+
+### Stable release
+
+To install flatland, run this command in your terminal:
+
+```console
+$ pip install flatland-rl
+```
+
+This is the preferred method to install flatland, as it will always install the most recent stable release.
+
+If you don't have `pip`_ installed, this `Python installation guide`_ can guide
+you through the process.
+
+.. _pip: https://pip.pypa.io
+.. _Python installation guide: http://docs.python-guide.org/en/latest/starting/installation/
+
+
+### From sources
+
+The sources for flatland can be downloaded from the `Gitlab repo`_.
+
+You can clone the public repository:
+```console
+$ git clone git@gitlab.aicrowd.com:flatland/flatland.git
+```
+
+Once you have a copy of the source, you can install it with:
+
+```console
+$ python setup.py install
+```
+
+.. _Gitlab repo: https://gitlab.aicrowd.com/flatland/flatland
+
+
+### Jupyter Canvas Widget
+If you work with jupyter notebook you need to install the Jupyer Canvas Widget. To install the Jupyter Canvas Widget read also
+https://github.com/Who8MyLunch/Jupyter_Canvas_Widget#installation
+
+## Basic Usage
+
+Basic usage of the RailEnv environment used by the Flatland Challenge
+
+
+```python
+import numpy as np
+import time
+from flatland.envs.rail_generators import complex_rail_generator
+from flatland.envs.schedule_generators import complex_schedule_generator
+from flatland.envs.rail_env import RailEnv
+from flatland.utils.rendertools import RenderTool
+
+NUMBER_OF_AGENTS = 10
+env = RailEnv(
+            width=20,
+            height=20,
+            rail_generator=complex_rail_generator(
+                                    nr_start_goal=10,
+                                    nr_extra=1,
+                                    min_dist=8,
+                                    max_dist=99999,
+                                    seed=0),
+            schedule_generator=complex_schedule_generator(),
+            number_of_agents=NUMBER_OF_AGENTS)
+
+env_renderer = RenderTool(env)
+
+def my_controller():
+    """
+    You are supposed to write this controller
+    """
+    _action = {}
+    for _idx in range(NUMBER_OF_AGENTS):
+        _action[_idx] = np.random.randint(0, 5)
+    return _action
+
+for step in range(100):
+
+    _action = my_controller()
+    obs, all_rewards, done, _ = env.step(_action)
+    print("Rewards: {}, [done={}]".format( all_rewards, done))
+    env_renderer.render_env(show=True, frames=False, show_observations=False)
+    time.sleep(0.3)
+```
+
+and **ideally** you should see something along the lines of
+
+![Flatland](https://i.imgur.com/VrTQVeM.gif)
+
+Best of Luck !!
+
+## Contributions
+Please follow the [Contribution Guidelines](http://flatland-rl-docs.s3-website.eu-central-1.amazonaws.com/contributing.html) for more details on how you can successfully contribute to the project. We enthusiastically look forward to your contributions.
+
+## Partners
+<a href="https://sbb.ch" target="_blank"><img src="https://i.imgur.com/OSCXtde.png" alt="SBB"/></a>
+<a href="https://www.aicrowd.com"  target="_blank"><img src="https://avatars1.githubusercontent.com/u/44522764?s=200&v=4" alt="AICROWD"/></a>
+
+
 
-.. image:: https://i.imgur.com/xgWGRse.gif
-  :align: center
-  :width: 600px
\ No newline at end of file

README.rst

-========
-Flatland
-========
-
-
-
-.. image:: https://gitlab.aicrowd.com/flatland/flatland/badges/master/pipeline.svg
-     :target: https://gitlab.aicrowd.com/flatland/flatland/pipelines
-     :alt: Test Running
-
-.. image:: https://gitlab.aicrowd.com/flatland/flatland/badges/master/coverage.svg
-     :target: https://gitlab.aicrowd.com/flatland/flatland/pipelines
-     :alt: Test Coverage
-
-'
-
-.. image:: https://i.imgur.com/0rnbSLY.gif
-  :width: 800
-  :align: center
-
-Flatland is a opensource toolkit for developing and comparing Multi Agent Reinforcement Learning algorithms in little (or ridiculously large !) gridworlds.
-The base environment is a two-dimensional grid in which many agents can be placed, and each agent must solve one or more navigational tasks in the grid world. More details about the environment and the problem statement can be found in the `official docs <http://flatland-rl-docs.s3-website.eu-central-1.amazonaws.com/>`_.
-
-This library was developed by `SBB <https://www.sbb.ch/en/>`_ , `AIcrowd <https://www.aicrowd.com/>`_ and numerous contributors and AIcrowd research fellows from the AIcrowd community.
-
-This library was developed specifically for the `Flatland Challenge <https://www.aicrowd.com/challenges/flatland-challenge>`_ in which we strongly encourage you to take part in.
-
-
-**NOTE This document is best viewed in the official documentation site at** `Flatland-RL Docs <http://flatland-rl-docs.s3-website.eu-central-1.amazonaws.com/readme.html>`_
-
-Contents
-===========
-* `Official Documentation <http://flatland-rl-docs.s3-website.eu-central-1.amazonaws.com/readme.html>`_
-* `About Flatland <http://flatland-rl-docs.s3-website.eu-central-1.amazonaws.com/about_flatland.html>`_
-* `Installation <http://flatland-rl-docs.s3-website.eu-central-1.amazonaws.com/installation.html>`_
-* `Getting Started <http://flatland-rl-docs.s3-website.eu-central-1.amazonaws.com/gettingstarted.html>`_
-* `Frequently Asked Questions <http://flatland-rl-docs.s3-website.eu-central-1.amazonaws.com/FAQ.html>`_
-* `Code Docs <http://flatland-rl-docs.s3-website.eu-central-1.amazonaws.com/modules.html>`_
-* `Contributing Guidelines <http://flatland-rl-docs.s3-website.eu-central-1.amazonaws.com/contributing.html>`_
-* `Discussion Forum <https://discourse.aicrowd.com/c/flatland-challenge>`_
-* `Issue Tracker <https://gitlab.aicrowd.com/flatland/flatland/issues/>`_
-
-Quick Start
-===========
-
-* Install `Anaconda <https://www.anaconda.com/distribution/>`_ by following the instructions `here <https://www.anaconda.com/distribution/>`_
-* Install the dependencies and the library
-
-.. code-block:: console
-
-    $ conda create python=3.6 --name flatland-rl
-    $ conda activate flatland-rl
-    $ conda install -c conda-forge cairosvg pycairo
-    $ conda install -c anaconda tk
-    $ pip install flatland-rl
-
-* Test that the installation works
-
-.. code-block:: console
-
-    $ flatland-demo
-
-
-Basic Usage
-============
-
-Basic usage of the RailEnv environment used by the Flatland Challenge
-
-.. code-block:: python
-
-    import numpy as np
-    import time
-    from flatland.envs.rail_generators import complex_rail_generator
-    from flatland.envs.schedule_generators import complex_schedule_generator
-    from flatland.envs.rail_env import RailEnv
-    from flatland.utils.rendertools import RenderTool
-
-    NUMBER_OF_AGENTS = 10
-    env = RailEnv(
-                width=20,
-                height=20,
-                rail_generator=complex_rail_generator(
-                                        nr_start_goal=10,
-                                        nr_extra=1,
-                                        min_dist=8,
-                                        max_dist=99999,
-                                        seed=0),
-                schedule_generator=complex_schedule_generator(),
-                number_of_agents=NUMBER_OF_AGENTS)
-
-    env_renderer = RenderTool(env)
-
-    def my_controller():
-        """
-        You are supposed to write this controller
-        """
-        _action = {}
-        for _idx in range(NUMBER_OF_AGENTS):
-            _action[_idx] = np.random.randint(0, 5)
-        return _action
-
-    for step in range(100):
-
-        _action = my_controller()
-        obs, all_rewards, done, _ = env.step(_action)
-        print("Rewards: {}, [done={}]".format( all_rewards, done))
-        env_renderer.render_env(show=True, frames=False, show_observations=False)
-        time.sleep(0.3)
-
-and **ideally** you should see something along the lines of
-
-.. image:: https://i.imgur.com/VrTQVeM.gif
-  :align: center
-  :width: 600px
-
-Best of Luck !!
-
-Contributions
-=============
-Flatland is an opensource project, and we very much value all and any contributions you make towards the project.
-Please follow the `Contribution Guidelines <http://flatland-rl-docs.s3-website.eu-central-1.amazonaws.com/contributing.html>`_ for more details on how you can successfully contribute to the project. We enthusiastically look forward to your contributions.
-
-Partners
-============
-.. image:: https://i.imgur.com/OSCXtde.png
-   :target: https://sbb.ch
-.. image:: https://avatars1.githubusercontent.com/u/44522764?s=200&v=4
-   :target: https://www.aicrowd.com
-
-
-Authors
-============
-
-* Christian Eichenberger <christian.markus.eichenberger@sbb.ch>
-* Adrian Egli <adrian.egli@sbb.ch>
-* Mattias Ljungström
-* Sharada Mohanty <mohanty@aicrowd.com>
-* Guillaume Mollard <guillaume.mollard2@gmail.com>
-* Erik Nygren <erik.nygren@sbb.ch>
-* Giacomo Spigler <giacomo.spigler@gmail.com>
-* Jeremy Watson
-
-
-Acknowledgements
-====================
-* Vaibhav Agrawal <theinfamouswayne@gmail.com>
-* Anurag Ghosh

changelog.md

@@ -38,7 +38,8 @@ The stock `ShortestPathPredictorForRailEnv` now respects the different agent spe
   - `rail_generator` now only returns the grid and optionally hints (a python dictionary); the hints are currently use for distance_map and communication of start and goal position in complex rail generator.
   - `schedule_generator` takes a `GridTransitionMap` and the number of agents and optionally the `agents_hints` field of the hints dictionary.
   - Inrodcution of types hints:
-```
+
+```python
 RailGeneratorProduct = Tuple[GridTransitionMap, Optional[Any]]
 RailGenerator = Callable[[int, int, int, int], RailGeneratorProduct]
 AgentPosition = Tuple[int, int]
@@ -62,7 +63,7 @@ To set up multiple speeds you have to modify the `agent.speed_data` within your
 Just like in real-worl transportation systems we introduced stochastic events to disturb normal traffic flow. Currently we implemented a malfunction process that stops agents at random time intervalls for a random time of duration.
 Currently the Flatland environment can be initiated with the following poisson process parameters:
 
-```
+```python
 # Use a the malfunction generator to break agents from time to time
 stochastic_data = {'prop_malfunction': 0.1,  # Percentage of defective agents
                    'malfunction_rate': 30,  # Rate of malfunction occurence

docs/03_tutorials.rst

+.. include:: tutorials/intro_observation_actions.rst
+.. include:: tutorials/intro_observationbuilder.rst

docs/03_tutorials_toc.rst

+Tutorials
+=========
+
+.. toctree::
+   :maxdepth: 2
+
+   03_tutorials

docs/04_specifications.rst

+.. include:: specifications/intro.rst
+.. include:: specifications/core.rst
+.. include:: specifications/railway.rst
+.. include:: specifications/rendering.rst
+.. include:: specifications/visualization.rst

docs/04_specifications_toc.rst

+Specifications
+==============
+
+
+.. toctree::
+   :maxdepth: 2
+
+   04_specifications
+
+

docs/changelog_index.rst → docs/07_changes.rst

@@ -4,5 +4,4 @@ Changes
 .. toctree::
    :maxdepth: 2
 
-   changelog.md
-   flatland_2.0.md
+   07_changes_include.rst

docs/07_changes_include.rst

+.. include:: ../changelog.rst
+.. include:: ../flatland_2.0.rst

docs/index.rst

 Welcome to flatland's documentation!
 ======================================
 
+.. include:: ../README.rst
+
 .. toctree::
    :maxdepth: 2
    :caption: Contents:
 
-   readme
-   installation
-   about_flatland
-   gettingstarted
-   intro_observationbuilder
-   intro_observation_actions
-   specifications_index
-   modules
-   FAQ
-   localevaluation
-   contributing
-   changelog_index
-   authors
-
-
-
+   01_readme
+   02_gettingstarted
+   03_tutorials_toc
+   04_specifications_toc
+   05_apidoc
+   06_contributing
+   07_changes
+   08_authors
 
 Indices and tables
 ==================

docs/installation.rst

-.. highlight:: shell
-
-============
-Installation
-============
-
-Software Runtime & Dependencies
--------------------------------
-
-This is the recommended way of installation and running flatland's dependencies.
-
-* Install `Anaconda <https://www.anaconda.com/distribution/>`_ by following the instructions `here <https://www.anaconda.com/distribution/>`_
-* Create a new conda environment 
-
-.. code-block:: console
-
-    $ conda create python=3.6 --name flatland-rl
-    $ conda activate flatland-rl
-
-* Install the necessary dependencies
-
-.. code-block:: console
-
-    $ conda install -c conda-forge cairosvg pycairo
-    $ conda install -c anaconda tk  
-
-
-Stable release
---------------
-
-To install flatland, run this command in your terminal:
-
-.. code-block:: console
-
-    $ pip install flatland-rl
-
-This is the preferred method to install flatland, as it will always install the most recent stable release.
-
-If you don't have `pip`_ installed, this `Python installation guide`_ can guide
-you through the process.
-
-.. _pip: https://pip.pypa.io
-.. _Python installation guide: http://docs.python-guide.org/en/latest/starting/installation/
-
-
-From sources
-------------
-
-The sources for flatland can be downloaded from the `Gitlab repo`_.
-
-You can clone the public repository:
-
-.. code-block:: console
-
-    $ git clone git@gitlab.aicrowd.com:flatland/flatland.git
-
-Once you have a copy of the source, you can install it with:
-
-.. code-block:: console
-
-    $ python setup.py install
-
-
-.. _Gitlab repo: https://gitlab.aicrowd.com/flatland/flatland
-
-
-Jupyter Canvas Widget
----------------------
-If you work with jupyter notebook you need to install the Jupyer Canvas Widget. To install the Jupyter Canvas Widget read also
-https://github.com/Who8MyLunch/Jupyter_Canvas_Widget#installation

docs/localevaluation.rst

-================
-Local Evaluation
-================
-
-This document explains you how to locally evaluate your submissions before making 
-an official submission to the competition.
-
-Requirements
-------------
-
-* **flatland-rl** : We expect that you have `flatland-rl` installed by following the instructions in  :doc:`installation`.
-
-* **redis** : Additionally you will also need to have  `redis installed <https://redis.io/topics/quickstart>`_ and **should have it running in the background.**
-
-Test Data
----------
-
-* **test env data** : You can `download and untar the test-env-data <https://www.aicrowd.com/challenges/flatland-challenge/dataset_files>`, at a location of your choice, lets say `/path/to/test-env-data/`. After untarring the folder, the folder structure should look something like:
-
-
-.. code-block:: console
-
-    .
-    └── test-env-data
-        ├── Test_0
-        │   ├── Level_0.pkl
-        │   └── Level_1.pkl
-        ├── Test_1
-        │   ├── Level_0.pkl
-        │   └── Level_1.pkl
-        ├..................
-        ├..................
-        ├── Test_8
-        │   ├── Level_0.pkl
-        │   └── Level_1.pkl
-        └── Test_9
-            ├── Level_0.pkl
-            └── Level_1.pkl
-
-Evaluation Service
-------------------
-
-* **start evaluation service** : Then you can start the evaluator by running : 
-
-.. code-block:: console
-
-    flatland-evaluator --tests /path/to/test-env-data/
-
-RemoteClient
-------------
-
-* **run client** : Some `sample submission code can be found in the starter-kit <https://github.com/AIcrowd/flatland-challenge-starter-kit/>`_, but before you can run your code locally using `FlatlandRemoteClient`, you will have to set the `AICROWD_TESTS_FOLDER` environment variable to the location where you previous untarred the folder with `the test-env-data`:
-
-
-.. code-block:: console
-
-    export AICROWD_TESTS_FOLDER="/path/to/test-env-data/"
-
-    # or on Windows :
-    # 
-    # set AICROWD_TESTS_FOLDER "\path\to\test-env-data\"
-
-    # and then finally run your code
-    python run.py
-