Merge branch '160-predictor-documentation' into 'master'

#160 predictor documentation

Closes #160

See merge request flatland/flatland!184

.gitignore

@@ -64,6 +64,10 @@ instance/
 
 # Sphinx documentation
 docs/_build/
+docs/flatland*.rst
+docs/modules.rst
+docs/changelog.md
+docs/flatland_2.0.md
 
 # PyBuilder
 target/
@@ -112,4 +116,4 @@ ENV/
 images/test/
 test_save.dat
 
-.visualizations
\ No newline at end of file
+.visualizations

Makefile

@@ -69,7 +69,7 @@ coverage: ## check code coverage quickly with the default Python
 docs: ## generate Sphinx HTML documentation, including API docs
 	rm -f docs/flatland*.rst
 	rm -f docs/modules.rst
-	sphinx-apidoc --force -a -e -o docs/ flatland
+	sphinx-apidoc --force -a -e -o docs/ flatland -H "Flatland Reference"
 	$(MAKE) -C docs clean
 	cp *.md docs
 	$(MAKE) -C docs html

changelog.md

-Keeping track of major Flatland Changes
-=======================================
+Changelog
+==========
 
 Changes since Flatland 0.3
 --------------------------

docs/FAQ.rst

@@ -41,7 +41,8 @@ Frequently Asked Questions (FAQs)
     .. _importlib-resources: https://importlib-resources.readthedocs.io/en/latest/
 
     Renders the scene into a image (screenshot)
+
     .. code-block:: python
 
-    renderer.gl.save_image("filename.bmp")
+        renderer.gl.save_image("filename.bmp")
 

docs/index.rst

@@ -11,13 +11,14 @@ Welcome to flatland's documentation!
    gettingstarted
    intro_observationbuilder
    specifications/specifications.md
-   localevaluation
    modules
    FAQ
+   localevaluation
    contributing
-   authors
    changelog.md
    flatland_2.0.md
+   authors
+
 
 
 

docs/intro_observationbuilder.rst

 =====
-Getting Started with custom observations
+Getting Started with custom observations and custom predictors
 =====
 
 Overview

docs/modules.rst

-flatland
-========
-
-.. toctree::
-   :maxdepth: 4
-
-   flatland

docs/specifications/specifications.md

-Flatland Environment Specifications
+Flatland Specs
 ==========================
 
-In a humand-readable language:
+What are **Flatland** specs about?
+---------------------------------
+In a humand-readable language, they provide
 * code base overview (hand-drawn concept)
 * key concepts (generators, envs) and how are they linked
 * link relevant code base
@@ -312,5 +314,22 @@ In case of the root node, the values are [0, 0, 0, 0, distance from agent to tar
 In case the target node is reached, the values are [0, 0, 0, 0, 0].
 
 
+## Predictors
+Predictors make predictions on future agents' moves based on the current state of the environment.
+They are decoupled from observation builders in order to be encapsulate the functionality and to make it re-usable.
+
+For instance, `TreeObsForRailEnv` optionally uses the predicted the predicted trajectories while exploring
+the branches of an agent's future moves to detect future conflicts.
+
+The general call structure is as follows:
+```
+RailEnv.step() 
+               -> ObservationBuilder.get_many() 
+                                                ->  self.predictor.get()
+                                                    self.get()
+                                                    self.get()
+                                                    ...
+```
+
 ## [Rendering](rendering)
 ## [Railway](railway)