[docs] rewrite #5175

richardliaw · 2019-07-11T19:14:24Z

What do these changes do?

TODOs:

Fix README
Guide for using Global State
Decide where TF guide goes, given the tf2.0
Convert examples into https://sphinx-gallery.github.io/

Punting but need to add:

Tips for first time users (https://docs.google.com/document/d/1Rv_NVdclEuAup4zdhTxtR8huawu7lX4ucds3sSiQlpQ/edit#)
Common Ray patterns
Performance compared to Dask
Performance compared to Celery
Performance compared to Multiprocessing/Joblib
Better fault tolerance guide (How to test if your application is fault tolerant)
Kubernetes Operator

Related issue number

Linter

I've run scripts/format.sh to lint the changes in this PR.

AmplabJenkins · 2019-07-11T19:45:03Z

Test FAILed.
Refer to this link for build results (access rights to CI server needed):
https://amplab.cs.berkeley.edu/jenkins//job/Ray-Perf-Integration-PRB/1625/
Test FAILed.

AmplabJenkins · 2019-07-11T22:04:25Z

Test PASSed.
Refer to this link for build results (access rights to CI server needed):
https://amplab.cs.berkeley.edu/jenkins//job/Ray-PRB/15316/
Test PASSed.

AmplabJenkins · 2019-07-17T22:03:55Z

Test FAILed.
Refer to this link for build results (access rights to CI server needed):
https://amplab.cs.berkeley.edu/jenkins//job/Ray-PRB/15450/
Test FAILed.

AmplabJenkins · 2019-07-17T23:42:33Z

Test PASSed.
Refer to this link for build results (access rights to CI server needed):
https://amplab.cs.berkeley.edu/jenkins//job/Ray-PRB/15451/
Test PASSed.

AmplabJenkins · 2019-07-18T00:19:25Z

Test PASSed.
Refer to this link for build results (access rights to CI server needed):
https://amplab.cs.berkeley.edu/jenkins//job/Ray-PRB/15453/
Test PASSed.

AmplabJenkins · 2019-07-18T00:24:30Z

Test PASSed.
Refer to this link for build results (access rights to CI server needed):
https://amplab.cs.berkeley.edu/jenkins//job/Ray-PRB/15452/
Test PASSed.

AmplabJenkins · 2019-07-18T00:28:10Z

Test PASSed.
Refer to this link for build results (access rights to CI server needed):
https://amplab.cs.berkeley.edu/jenkins//job/Ray-PRB/15455/
Test PASSed.

edoakes · 2019-07-18T00:27:31Z

doc/source/index.rst

+
+Ray Ecosystem
+-------------
+
 Ray comes with libraries that accelerate deep learning and reinforcement learning development:


not sure about the phrasing "comes with" - makes them sound like Ray add-ons instead of standalone projects built on Ray

edoakes · 2019-07-18T00:28:02Z

doc/source/index.rst

 Ray comes with libraries that accelerate deep learning and reinforcement learning development:

 - `Tune`_: Scalable Hyperparameter Search
 - `RLlib`_: Scalable Reinforcement Learning
 - `Distributed Training <distributed_training.html>`__

+Other projects in development:
+


Suggested change

TODO: add short descriptions and progress

doc/source/index.rst

edoakes · 2019-07-18T00:29:54Z

doc/source/index.rst

@@ -103,48 +96,71 @@ Ray comes with libraries that accelerate deep learning and reinforcement learnin
   rllib-dev.rst
   rllib-package-ref.rst

+.. toctree::


isn't this going to its own page? or is this just temporary?

edoakes · 2019-07-18T00:30:32Z

doc/source/index.rst


+   install-source.rst
+   contrib.rst


Suggested change

contrib.rst

contributing.rst

nit: other names are spelled out

AmplabJenkins · 2019-07-18T01:22:03Z

Test FAILed.
Refer to this link for build results (access rights to CI server needed):
https://amplab.cs.berkeley.edu/jenkins//job/Ray-PRB/15457/
Test FAILed.

AmplabJenkins · 2019-07-18T02:46:54Z

Test PASSed.
Refer to this link for build results (access rights to CI server needed):
https://amplab.cs.berkeley.edu/jenkins//job/Ray-PRB/15456/
Test PASSed.

AmplabJenkins · 2019-07-18T22:12:40Z

Test FAILed.
Refer to this link for build results (access rights to CI server needed):
https://amplab.cs.berkeley.edu/jenkins//job/Ray-Perf-Integration-PRB/1715/
Test FAILed.

AmplabJenkins · 2019-07-19T00:59:17Z

Test PASSed.
Refer to this link for build results (access rights to CI server needed):
https://amplab.cs.berkeley.edu/jenkins//job/Ray-Perf-Integration-PRB/1716/
Test PASSed.

AmplabJenkins · 2019-07-24T01:09:46Z

Test FAILed.
Refer to this link for build results (access rights to CI server needed):
https://amplab.cs.berkeley.edu/jenkins//job/Ray-PRB/15602/
Test FAILed.

AmplabJenkins · 2019-07-24T02:46:01Z

Test PASSed.
Refer to this link for build results (access rights to CI server needed):
https://amplab.cs.berkeley.edu/jenkins//job/Ray-PRB/15601/
Test PASSed.

AmplabJenkins · 2019-07-24T08:22:23Z

Test FAILed.
Refer to this link for build results (access rights to CI server needed):
https://amplab.cs.berkeley.edu/jenkins//job/Ray-PRB/15608/
Test FAILed.

AmplabJenkins · 2019-07-31T00:44:14Z

Test PASSed.
Refer to this link for build results (access rights to CI server needed):
https://amplab.cs.berkeley.edu/jenkins//job/Ray-PRB/15812/
Test PASSed.

robertnishihara

I didn't get very far. Awesome work so far, this is a huge improvement. Still working through it, but wanted to leave partial comments.

robertnishihara · 2019-07-30T02:48:36Z

doc/source/index.rst

+-----------
+
+.. code-block:: python
+


I'd suggest adding the import ray as well so people can copy/paste.

robertnishihara · 2019-07-31T04:44:11Z

doc/source/index.rst

+
+Ray programs can run on a single machine, and can also seamlessly scale to large clusters. To execute the above Ray script in the cloud, just download `this configuration file <https://github.com/ray-project/ray/blob/master/python/ray/autoscaler/aws/example-full.yaml>`__, and run:
+
+``ray submit [CLUSTER.YAML] example.py --start``


I love what you're doing here. I think it will be substantially easier for users if it can be fully done with copy/paste. E.g.,

wget https://.../example-full.yaml # Get the cluster config file. wget https://.../example.py # Get the example script. ray submit example-full.yaml example.py --start # Run the script on the cluster.

robertnishihara · 2019-07-31T04:57:00Z

doc/source/index.rst

+
+``ray submit [CLUSTER.YAML] example.py --start``
+
+See more details in the `Cluster Launch page <autoscaling.html>`_.


Suggested change

See more details in the `Cluster Launch page <autoscaling.html>`_.

Read more about `launching clusters <autoscaling.html>`_.

doc/source/index.rst

robertnishihara · 2019-07-31T05:08:13Z

doc/source/index.rst

+-----------------
+
+`RLlib`_ is an open-source library for reinforcement learning that offers both high scalability and a unified API for a variety of applications.
+


Add a link to the main Tune documentation.

Ok, I missed the fact that the initial word Tune is a link.

doc/source/index.rst

robertnishihara · 2019-07-31T05:26:10Z

doc/source/index.rst

+            done = self.cur_pos >= self.end_pos
+            return [self.cur_pos], 1 if done else 0, done, {}
+
+    tune.run(


This example takes too long to run, can we make it finish in under 30 seconds?

I think this is expected for RL.

I agree that for a real RL application it will run for a long time, but this is code that people will be copying and pasting from the browser into the terminal just to verify that it runs (e.g., that they managed to install it properly) and it's a better experience if it runs to completion instead of the user having to manually kill it.

robertnishihara · 2019-07-31T05:37:01Z

doc/source/installation.rst

@@ -42,103 +42,20 @@ Here are links to the latest wheels (which are built off of master). To install
 .. _`MacOS Python 3.5`: https://s3-us-west-2.amazonaws.com/ray-wheels/latest/ray-0.8.0.dev2-cp35-cp35m-macosx_10_6_intel.whl
 .. _`MacOS Python 2.7`: https://s3-us-west-2.amazonaws.com/ray-wheels/latest/ray-0.8.0.dev2-cp27-cp27m-macosx_10_6_intel.whl



Can you also add instructions for installing Ray from any particular recent commit? E.g.,

Suggested change

To install Ray from any recent commit, do the following.

.. code-block:: bash

RAY_COMMIT=63a6b0e710fded230f340a237e55085fb4ace4e9

RAY_VERSION=0.8.0.dev3 # You can find this in python/ray/__init__.py.

RAY_BRANCH=master

pip install -U https://s3-us-west-2.amazonaws.com/ray-wheels/$RAY_BRANCH/$RAY_COMMIT/ray-$RAY_VERSION-cp36-cp36m-manylinux1_x86_64.whl

Actually, the above doesn't quite work because we also need to modify the wheel for Mac/Linux and different Python versions. Maybe it's best to put it in a simple script and then link to it from here.

doc/source/installation.rst

AmplabJenkins · 2019-08-01T19:55:43Z

Test FAILed.
Refer to this link for build results (access rights to CI server needed):
https://amplab.cs.berkeley.edu/jenkins//job/Ray-PRB/15895/
Test FAILed.

AmplabJenkins · 2019-08-01T23:32:36Z

Test PASSed.
Refer to this link for build results (access rights to CI server needed):
https://amplab.cs.berkeley.edu/jenkins//job/Ray-PRB/15904/
Test PASSed.

AmplabJenkins · 2019-08-02T02:40:31Z

Test PASSed.
Refer to this link for build results (access rights to CI server needed):
https://amplab.cs.berkeley.edu/jenkins//job/Ray-PRB/15911/
Test PASSed.

AmplabJenkins · 2019-08-02T03:42:35Z

Test PASSed.
Refer to this link for build results (access rights to CI server needed):
https://amplab.cs.berkeley.edu/jenkins//job/Ray-PRB/15914/
Test PASSed.

Co-Authored-By: Robert Nishihara <[email protected]>

ericl

This LGTM. Let's merge and iterate.

AmplabJenkins · 2019-08-05T23:52:03Z

Test PASSed.
Refer to this link for build results (access rights to CI server needed):
https://amplab.cs.berkeley.edu/jenkins//job/Ray-PRB/15989/
Test PASSed.

AmplabJenkins · 2019-08-06T06:04:00Z

Test PASSed.
Refer to this link for build results (access rights to CI server needed):
https://amplab.cs.berkeley.edu/jenkins//job/Ray-PRB/16005/
Test PASSed.

raulchen · 2019-08-06T12:46:25Z

@richardliaw, the CI lint failure on the master branch seems related to this PR. Can you fix it? thanks.

robertnishihara · 2019-08-01T18:07:55Z

doc/source/walkthrough.rst

+   2. Fetching results (object IDs) [``ray.put``, ``ray.get``, ``ray.wait``]
+   3. Using remote classes (actors) [``ray.remote``]
+
+.. list-table:: Title


What's the plan for this table?

robertnishihara · 2019-08-01T18:25:46Z

doc/source/walkthrough.rst

+
+**Object IDs** can also be passed into remote functions. When the function actually gets executed, **the argument will be a retrieved as a regular Python object**.
+
+.. code:: python


This block doesn't run.

robertnishihara · 2019-08-01T19:05:03Z

doc/source/walkthrough.rst

+    1. **Invocation:** The regular version is called with ``regular_function()``, whereas the remote version is called with ``remote_function.remote()``.
+    2. **Return values:** ``regular_function`` immediately executes and returns ``1``, whereas ``remote_function`` immediately returns an object ID (a future) and then creates a task that will be executed on a worker process. The result can be retrieved with ``ray.get``.
+
+    .. code:: python


For as many of these as possible, I would remove the >>> because it makes copy and paste harder. For example, this code block could be rewritten as

regular_function() # 1 remote_function.remote() # ObjectID(1c80d6937802cd7786ad25e50caf2f023c95e350) ray.get(remote_function.remote()) # 1

I'd like to push back on this - I think this is non-standard and not as reader friendly as you expect, especially for those who are glancing over documentation.

For examples, this is definitely necessary.

On the other hand, I can leave a note to show that it's actually possible to copy and paste these: https://numpydoc.readthedocs.io/en/latest/format.html#sections

In the future, we can incorporate a modded copybutton: https://docs.scipy.org/doc/numpy-1.16.0/reference/generated/numpy.random.randint.html
https://github.com/scipy/scipy-sphinx-theme/blob/c466764e2231ba132c09826b5b138fffa1cfcec3/_theme/scipy/static/js/copybutton.js

The reason why it's not reader friendly is because the in-line comment is not a standard signifier for return value. However >>> and subsequent lines are standard for python interpreter output.

robertnishihara · 2019-08-01T22:27:07Z

doc/source/index.rst

+            done = self.cur_pos >= self.end_pos
+            return [self.cur_pos], 1 if done else 0, done, {}
+
+    tune.run(


I agree that for a real RL application it will run for a long time, but this is code that people will be copying and pasting from the browser into the terminal just to verify that it runs (e.g., that they managed to install it properly) and it's a better experience if it runs to completion instead of the user having to manually kill it.

robertnishihara · 2019-08-01T23:18:56Z

doc/source/installation.rst

@@ -41,104 +42,3 @@ Here are links to the latest wheels (which are built off of master). To install
 .. _`MacOS Python 3.6`: https://s3-us-west-2.amazonaws.com/ray-wheels/latest/ray-0.8.0.dev2-cp36-cp36m-macosx_10_6_intel.whl
 .. _`MacOS Python 3.5`: https://s3-us-west-2.amazonaws.com/ray-wheels/latest/ray-0.8.0.dev2-cp35-cp35m-macosx_10_6_intel.whl
 .. _`MacOS Python 2.7`: https://s3-us-west-2.amazonaws.com/ray-wheels/latest/ray-0.8.0.dev2-cp27-cp27m-macosx_10_6_intel.whl
-
-
-Building Ray from source


I see that you moved this to a different file (which doesn't appear to be linked to from anywhere). However, why not leave it here? This is the obvious place Ray developers would look for it.

I'll move this back.

robertnishihara · 2019-08-01T23:19:12Z

doc/source/installation.rst

-
-.. code-block:: bash
-
-  conda install libgcc


This is probably not needed anymore though.

robertnishihara · 2019-08-01T23:34:54Z

doc/source/inspect.rst

+  that it can submit tasks to its raylet and get objects from the object
+  store, but it is different in that the raylet will not assign tasks to
+  the driver to be executed.
+- A **Redis server** maintains much of the system's state. For example, it keeps


There are actually multiple Redis servers.

Also, there are some monitor processes (on the head node) and log monitor process (on each machine).

robertnishihara · 2019-08-01T23:35:44Z

doc/source/inspect.rst

+
+To get information about the current available resource capacity of your cluster, you can use ``ray.available_resources()``.
+
+.. autofunction:: ray.cluster_resources


Suggested change

.. autofunction:: ray.cluster_resources

.. autofunction:: ray.available_resources

robertnishihara · 2019-08-01T23:36:35Z

doc/source/inspect.rst

+    :noindex:
+
+
+Object Information


Not sure if this will be useful to people, I'd probably omit it.

robertnishihara · 2019-08-01T23:47:17Z

doc/source/user-profiling.rst

-Profiling for Ray Users
-=======================
+How-to: Profile Ray programs
+============================

 This document is intended for users of Ray who want to know how to evaluate


This page either needs to be improved a lot or scrapped.

However, the timeline stuff is super important, so I would keep that (maybe make it its own page).

richardliaw · 2019-08-06T22:03:12Z

@robertnishihara I'll make a separate PR for this as this was merged a bit prematurely, though there's no need to revert.

rewrite

281aafc

robertnishihara changed the title ~~[docs] rewrite~~ [WIP] [docs] rewrite Jul 12, 2019

richardliaw added 7 commits July 17, 2019 13:28

Merge branch 'master' into docsrevamp

590b0d1

rst

3847cd9

moremodifications

1b90922

revert

0f081fa

revamptune

65ff355

revert

009ed62

update

5f17fb9

compile

4e69c89

first framework

66b0eee

edoakes reviewed Jul 18, 2019

View reviewed changes

richardliaw added 3 commits July 23, 2019 15:06

Merge branch 'master' into docsrevamp

076fa42

resources

5e347d4

sym

6dabb43

ln

257d172

ericl self-assigned this Jul 30, 2019

ericl added 2 commits July 30, 2019 15:02

changes

b016a59

Merge remote-tracking branch 'upstream/master' into docsrevamp

1331fa9

robertnishihara reviewed Jul 31, 2019

View reviewed changes

Some updates to installation and walkthrough.

fc5d396

robertnishihara added 2 commits August 1, 2019 13:01

Update actor documentation.

4964268

Improve GPU documentation.

e202735

Small improvements

95d3faf

richardliaw and others added 4 commits August 5, 2019 13:21

Update doc/source/index.rst

9f521e9

Co-Authored-By: Robert Nishihara <[email protected]>

Update doc/source/index.rst

6f8a07c

Co-Authored-By: Robert Nishihara <[email protected]>

spacing

e0620a7

Merge branch 'docsrevamp' of github.com:richardliaw/ray into docsrevamp

ea8909a

ericl approved these changes Aug 5, 2019

View reviewed changes

Merge remote-tracking branch 'upstream/master' into docsrevamp

5a67db3

ericl merged commit a08ea09 into ray-project:master Aug 6, 2019

This was referenced Aug 6, 2019

[docs] Update tutorial page in documentation. #3487

Closed

[docs] ray.wait not covered in tutorial.html? #2486

Closed

robertnishihara reviewed Aug 6, 2019

View reviewed changes

robertnishihara mentioned this pull request Aug 6, 2019

All the doc links are broken :-( #5388

Closed

edoakes pushed a commit to edoakes/ray that referenced this pull request Aug 9, 2019

[docs] rewrite (ray-project#5175)

4cc3cff

richardliaw mentioned this pull request Oct 7, 2019

Add documentation on using Ray with PyTorch. #968

Closed


		Ray programs can run on a single machine, and can also seamlessly scale to large clusters. To execute the above Ray script in the cloud, just download `this configuration file <https://github.com/ray-project/ray/blob/master/python/ray/autoscaler/aws/example-full.yaml>`__, and run:

		``ray submit [CLUSTER.YAML] example.py --start``


		``ray submit [CLUSTER.YAML] example.py --start``

		See more details in the `Cluster Launch page <autoscaling.html>`_.

	See more details in the `Cluster Launch page <autoscaling.html>`_.
	Read more about `launching clusters <autoscaling.html>`_.

		-----------------

		`RLlib`_ is an open-source library for reinforcement learning that offers both high scalability and a unified API for a variety of applications.

		@@ -42,103 +42,20 @@ Here are links to the latest wheels (which are built off of master). To install
		.. _`MacOS Python 3.5`: https://s3-us-west-2.amazonaws.com/ray-wheels/latest/ray-0.8.0.dev2-cp35-cp35m-macosx_10_6_intel.whl
		.. _`MacOS Python 2.7`: https://s3-us-west-2.amazonaws.com/ray-wheels/latest/ray-0.8.0.dev2-cp27-cp27m-macosx_10_6_intel.whl

+To install Ray from any recent commit, do the following.
+.. code-block:: bash
+  RAY_COMMIT=63a6b0e710fded230f340a237e55085fb4ace4e9
+  RAY_VERSION=0.8.0.dev3  # You can find this in python/ray/__init__.py.
+  RAY_BRANCH=master
+  pip install -U https://s3-us-west-2.amazonaws.com/ray-wheels/$RAY_BRANCH/$RAY_COMMIT/ray-$RAY_VERSION-cp36-cp36m-manylinux1_x86_64.whl


		Object IDs can also be passed into remote functions. When the function actually gets executed, the argument will be a retrieved as a regular Python object.

		.. code:: python


		To get information about the current available resource capacity of your cluster, you can use ``ray.available_resources()``.

		.. autofunction:: ray.cluster_resources

	.. autofunction:: ray.cluster_resources
	.. autofunction:: ray.available_resources

[docs] rewrite #5175

[docs] rewrite #5175

Conversation

richardliaw commented Jul 11, 2019 • edited Loading

What do these changes do?

TODOs:

Related issue number

Linter

AmplabJenkins commented Jul 11, 2019

AmplabJenkins commented Jul 11, 2019

AmplabJenkins commented Jul 17, 2019

AmplabJenkins commented Jul 17, 2019

AmplabJenkins commented Jul 18, 2019

AmplabJenkins commented Jul 18, 2019

AmplabJenkins commented Jul 18, 2019

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

AmplabJenkins commented Jul 18, 2019

AmplabJenkins commented Jul 18, 2019

AmplabJenkins commented Jul 18, 2019

AmplabJenkins commented Jul 19, 2019

AmplabJenkins commented Jul 24, 2019

AmplabJenkins commented Jul 24, 2019

AmplabJenkins commented Jul 24, 2019

AmplabJenkins commented Jul 31, 2019

robertnishihara left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

AmplabJenkins commented Aug 1, 2019

AmplabJenkins commented Aug 1, 2019

AmplabJenkins commented Aug 2, 2019

AmplabJenkins commented Aug 2, 2019

ericl left a comment

Choose a reason for hiding this comment

AmplabJenkins commented Aug 5, 2019

AmplabJenkins commented Aug 6, 2019

raulchen commented Aug 6, 2019

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

richardliaw commented Aug 6, 2019

richardliaw commented Jul 11, 2019 •

edited

Loading