[tune] Add internal implementation overview + image for task timeline (#1254)

python/ray/rllib/README.rst

@@ -1,5 +1,5 @@
-RLLib: Ray's modular and scalable reinforcement learning library
-================================================================
+RLLib: A Scalable Reinforcement Learning Library
+================================================
 
 Getting Started
 ---------------
@@ -28,4 +28,4 @@ The available algorithms are:
    `A3C <https://arxiv.org/abs/1602.01783>`__ based on `the OpenAI
    starter agent <https://github.com/openai/universe-starter-agent>`__.
 
-Documentation can be `found here <http://ray.readthedocs.io/en/latest/rllib.html>`__.
+User documentation can be `found here <http://ray.readthedocs.io/en/latest/rllib.html>`__.

python/ray/tune/README.rst

@@ -3,4 +3,26 @@ Ray.tune: Efficient distributed hyperparameter search
 
 Ray.tune is a hyperparameter tuning tool for long-running tasks such as RL and deep learning training.
 
-Documentation can be `found here <https://github.com/ray-project/ray/blob/master/doc/source/tune.rst>`__.
+User documentation can be `found here <http://ray.readthedocs.io/en/latest/tune.html>`__.
+
+Implementation overview
+-----------------------
+
+At a high level, Ray.tune takes in JSON experiment configs (e.g. that defines the grid or random search)
+and compiles them into a number of `Trial` objects. It schedules trials on the Ray cluster using a given
+`TrialScheduler` implementation (e.g. median stopping rule or HyperBand).
+
+This is implemented as follows:
+
+-  `variant_generator.py <https://github.com/ray-project/ray/blob/master/python/ray/tune/variant_generator.py>`__
+   parses the config and generates the trial variants.
+
+-  `trial.py <https://github.com/ray-project/ray/blob/master/python/ray/tune/trial.py>`__ manages the lifecycle
+   of the Ray actor responsible for executing the trial.
+
+-  `trial_runner.py <https://github.com/ray-project/ray/blob/master/python/ray/tune/tune.py>`__ tracks scheduling
+   state for all the trials of an experiment. TrialRunners are usually
+   created automatically by ``run_experiments(experiment_json)``, which parses and starts the experiments.
+
+-  `trial_scheduler.py <https://github.com/ray-project/ray/blob/master/python/ray/tune/trial_scheduler.py>`__
+   plugs into TrialRunner to implement custom prioritization or early stopping algorithms.