From d923423b3145b0b1a537f5a0cfd344ed410cebf6 Mon Sep 17 00:00:00 2001
From: SP Mohanty <spmohanty91@gmail.com>
Date: Wed, 3 Jul 2019 09:08:47 +0200
Subject: [PATCH] Streamline docs
---
README.rst | 176 ++++++++++++++++--------------------------
docs/about.rst | 39 ++++++++++
docs/index.rst | 1 +
docs/installation.rst | 6 ++
4 files changed, 113 insertions(+), 109 deletions(-)
create mode 100644 docs/about.rst
diff --git a/README.rst b/README.rst
index 2b6b3102..42934d82 100644
--- a/README.rst
+++ b/README.rst
@@ -14,113 +14,43 @@ Flatland
.. image:: https://i.imgur.com/rKGEmsk.gif
:align: center
-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.
-In general, agents can freely navigate from cell to cell. However, cell-to-cell navigation can be restricted by transition maps.
-Each cell can hold an own transition map. By default, each cell has a default transition map defined which allows all transitions to its
-eight neighbor cells (go up and left, go up, go up and right, go right, go down and right, go down, go down and left, go left).
-So, the agents can freely move from cell to cell.
+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 `here <http://flatland-rl-docs.s3-website.eu-central-1.amazonaws.com/>`_.
-The general purpose of the implementation allows to implement any kind of two-dimensional gird based environments.
-It can be used for many learning task where a two-dimensional grid could be the base of the environment.
+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.
-Flatland delivers a python implementation which can be easily extended. And it provides different baselines for different environments.
-Each environment enables an interesting task to solve. For example, the mutli-agent navigation task for railway train dispatching is a very exciting topic.
-It can be easily extended or adapted to the airplane landing problem. This can further be the basic implementation for many other tasks in transportation and logistics.
+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.
-Mapping a railway infrastructure into a grid world is an excellent example showing how the movement of an agent must be restricted.
-As trains can normally not run backwards and they have to follow rails the transition for one cell to the other depends also on train's orientation, respectively on train's travel direction.
-Trains can only change the traveling path at switches. There are two variants of switches. The first kind of switch is the splitting "switch", where trains can change rails and in consequence they can change the traveling path.
-The second kind of switch is the fusion switch, where train can change the sequence. That means two rails come together. Thus, the navigation behavior of a train is very restricted.
-The railway planning problem where many agents share same infrastructure is a very complex problem.
+Contents
+===========
+* `Official Documentation <http://flatland-rl-docs.s3-website.eu-central-1.amazonaws.com/readme.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/>`_
-Furthermore, trains have a departing location where they cannot depart earlier than the committed departure time.
-Then they must arrive at destination not later than the committed arrival time. This makes the whole planning problem
-very complex. In such a complex environment cooperation is essential. Thus, agents must learn to cooperate in a way that all trains (agents) arrive on time.
+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
-.. image:: https://i.imgur.com/pucB84T.gif
- :align: center
- :width: 600px
-
-.. image:: https://i.imgur.com/xgWGRse.gif
- :align: center
- :width: 600px
-
-
-Getting Started
-===============
-
-Online Docs
-------------
-
-The documentation for the latest code on the master branch is found at : `flatland-rl-docs <http://flatland-rl-docs.s3-website.eu-central-1.amazonaws.com/>`_
-
-The documentation includes a few tutorials at : `Getting Started <http://flatland-rl-docs.s3-website.eu-central-1.amazonaws.com/gettingstarted.html>`_
-
-Run Notebooks with Examples with one Click
-------------------------------------------
-Under getting_started, there are two scripts ::
+.. code-block:: console
- getting_started/run_notebooks.bat
- getting_started/run_notebooks.sh
-
-They require git and Python>=3.6 installed with venv (python3-venv has to be installed under Linux).
-They create a virtual environment, install Flatland and all dependencies into into and start they Jupyter notebooks in your browser.
-
-
-Generate Docs
---------------
-
-The docs have a lot more details about how to interact with this codebase. ::
-
- git clone git@gitlab.aicrowd.com:flatland/flatland.git
- cd flatland
- pip install -r requirements_dev.txt
-
-* On, Linux and macOS ::
-
- make docs
-
-* On, Windows ::
-
- python setup.py develop (or)
- python setup.py install
- python make_docs.py
-
-
-Installation
-============
+ $ 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
-Stable Release
---------------
+* Test that the installation works
-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 <https://pip.pypa.io/en/stable/>`_ installed, this `Python installation guide <https://docs.python-guide.org/starting/installation/>`_ can guide you through the process.
-
-
-From Sources
-------------
-The sources for flatland can be downloaded from the `Gitlab repo <https://gitlab.aicrowd.com/flatland/flatland>`_.
-
-You can clone the public repository ::
-
- $ git clone git@gitlab.aicrowd.com:flatland/flatland.git
-
-Once you have a copy of the source, you can install it with ::
-
- $ python setup.py install
-
-
-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
+ $ flatland-demo
Basic Usage
@@ -135,30 +65,58 @@ Basic usage of the RailEnv environment used by the Flatland Challenge
from flatland.envs.generators import complex_rail_generator
from flatland.envs.rail_env import RailEnv
from flatland.utils.rendertools import RenderTool
-
+
+ NUMBER_OF_AGENTS = 10
env = RailEnv(
- width=7,
- height=7,
+ width=20,
+ height=20,
rail_generator=complex_rail_generator(
nr_start_goal=10,
nr_extra=1,
min_dist=8,
max_dist=99999,
seed=0),
- number_of_agents=2)
-
+ 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):
- obs, all_rewards, done, _ = env.step(
- {
- 0:np.random.randint(0, 5),
- 1:np.random.randint(0, 5)
- })
- print("Rewards: {}, [done={}]".format( all_rewards, done)
+
+ _action = my_controller()
+ obs, all_rewards, done, _ = env.step(_action)
+ print("Rewards: {}, [done={}]".format( all_rewards, done))
env_renderer.renderEnv(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/xgWGRse.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://upload.wikimedia.org/wikipedia/commons/thumb/0/00/Sbb-logo.svg/1418px-Sbb-logo.svg.png
+ :target: https://sbb.ch
+.. image:: https://avatars1.githubusercontent.com/u/44522764?s=200&v=4
+ :target: https://www.aicrowd.com
+
Authors
============
diff --git a/docs/about.rst b/docs/about.rst
new file mode 100644
index 00000000..ce075205
--- /dev/null
+++ b/docs/about.rst
@@ -0,0 +1,39 @@
+.. image:: https://i.imgur.com/rKGEmsk.gif
+ :align: center
+
+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.
+In general, agents can freely navigate from cell to cell. However, cell-to-cell navigation can be restricted by transition maps.
+Each cell can hold an own transition map. By default, each cell has a default transition map defined which allows all transitions to its
+eight neighbor cells (go up and left, go up, go up and right, go right, go down and right, go down, go down and left, go left).
+So, the agents can freely move from cell to cell.
+
+The general purpose of the implementation allows to implement any kind of two-dimensional gird based environments.
+It can be used for many learning task where a two-dimensional grid could be the base of the environment.
+
+Flatland delivers a python implementation which can be easily extended. And it provides different baselines for different environments.
+Each environment enables an interesting task to solve. For example, the mutli-agent navigation task for railway train dispatching is a very exciting topic.
+It can be easily extended or adapted to the airplane landing problem. This can further be the basic implementation for many other tasks in transportation and logistics.
+
+Mapping a railway infrastructure into a grid world is an excellent example showing how the movement of an agent must be restricted.
+As trains can normally not run backwards and they have to follow rails the transition for one cell to the other depends also on train's orientation, respectively on train's travel direction.
+Trains can only change the traveling path at switches. There are two variants of switches. The first kind of switch is the splitting "switch", where trains can change rails and in consequence they can change the traveling path.
+The second kind of switch is the fusion switch, where train can change the sequence. That means two rails come together. Thus, the navigation behavior of a train is very restricted.
+The railway planning problem where many agents share same infrastructure is a very complex problem.
+
+Furthermore, trains have a departing location where they cannot depart earlier than the committed departure time.
+Then they must arrive at destination not later than the committed arrival time. This makes the whole planning problem
+very complex. In such a complex environment cooperation is essential. Thus, agents must learn to cooperate in a way that all trains (agents) arrive on time.
+
+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.
+
+
+.. image:: https://i.imgur.com/pucB84T.gif
+ :align: center
+ :width: 600px
+
+.. image:: https://i.imgur.com/xgWGRse.gif
+ :align: center
+ :width: 600px
\ No newline at end of file
diff --git a/docs/index.rst b/docs/index.rst
index 791d40c0..c1945553 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -6,6 +6,7 @@ Welcome to flatland's documentation!
:caption: Contents:
readme
+ about
installation
gettingstarted
modules
diff --git a/docs/installation.rst b/docs/installation.rst
index 148fe5b5..99bee32b 100644
--- a/docs/installation.rst
+++ b/docs/installation.rst
@@ -62,3 +62,9 @@ Once you have a copy of the source, you can install it with:
.. _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
--
GitLab