[docs] Render ActorPool documentation, etc (#9433)

doc/examples/overview.rst

@@ -1,8 +1,7 @@
 Ray Tutorials and Examples
 ==========================
 
-Get started with Ray, Tune, and RLlib with these notebooks that you can run online in CoLab or Binder:
- * `Ray Tutorial Notebooks <https://github.com/ray-project/tutorial>`__
+Get started with Ray, Tune, and RLlib with these notebooks that you can run online in CoLab or Binder: `Ray Tutorial Notebooks <https://github.com/ray-project/tutorial>`__
 
 .. toctree::
    :hidden:
@@ -17,9 +16,6 @@ Get started with Ray, Tune, and RLlib with these notebooks that you can run onli
    plot_example-lm.rst
 
 
-Example Gallery
----------------
-
 .. customgalleryitem::
    :tooltip: Build a simple parameter server using Ray.
    :figure: /images/param_actor.png

doc/source/package-ref.rst

@@ -1,51 +1,168 @@
 Ray Package Reference
 =====================
 
+Python API
+----------
+
+.. _ray-init-ref:
+
+ray.init
+~~~~~~~~
+
 .. autofunction:: ray.init
 
+.. _ray-is_initialized-ref:
+
+ray.is_initialized
+~~~~~~~~~~~~~~~~~~
+
 .. autofunction:: ray.is_initialized
 
+.. _ray-remote-ref:
+
+ray.remote
+~~~~~~~~~~
+
 .. autofunction:: ray.remote
 
+.. _ray-get-ref:
+
+ray.get
+~~~~~~~
+
 .. autofunction:: ray.get
 
+.. _ray-wait-ref:
+
+ray.wait
+~~~~~~~~
+
 .. autofunction:: ray.wait
 
+.. _ray-put-ref:
+
+ray.put
+~~~~~~~
+
 .. autofunction:: ray.put
 
+.. _ray-kill-ref:
+
+ray.kill
+~~~~~~~~
+
 .. autofunction:: ray.kill
 
+.. _ray-cancel-ref:
+
+ray.cancel
+~~~~~~~~~~
+
 .. autofunction:: ray.cancel
 
+.. _ray-get_gpu_ids-ref:
+
+ray.get_gpu_ids
+~~~~~~~~~~~~~~~
+
 .. autofunction:: ray.get_gpu_ids
 
+.. _ray-get_resource_ids-ref:
+
+ray.get_resource_ids
+~~~~~~~~~~~~~~~~~~~~
+
 .. autofunction:: ray.get_resource_ids
 
+.. _ray-get_webui_url-ref:
+
+ray.get_webui_url
+~~~~~~~~~~~~~~~~~
+
 .. autofunction:: ray.get_webui_url
 
+.. _ray-shutdown-ref:
+
+ray.shutdown
+~~~~~~~~~~~~
+
 .. autofunction:: ray.shutdown
 
+
+.. _ray-register_custom_serializer-ref:
+
+ray.register_custom_serializer
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
 .. autofunction:: ray.register_custom_serializer
 
+.. _ray-profile-ref:
+
+ray.profile
+~~~~~~~~~~~
+
 .. autofunction:: ray.profile
 
+.. _ray-method-ref:
+
+ray.method
+~~~~~~~~~~
+
 .. autofunction:: ray.method
 
-Inspect the Cluster State
--------------------------
+ray.util.ActorPool
+~~~~~~~~~~~~~~~~~~
+
+.. autoclass:: ray.util.ActorPool
+   :members:
+
+.. _ray-nodes-ref:
+
+ray.nodes
+~~~~~~~~~
 
 .. autofunction:: ray.nodes
 
+.. _ray-objects-ref:
+
+ray.objects
+~~~~~~~~~~~
+
 .. autofunction:: ray.objects
 
+.. _ray-timeline-ref:
+
+ray.timeline
+~~~~~~~~~~~~
+
 .. autofunction:: ray.timeline
 
+.. _ray-object_transfer_timeline-ref:
+
+ray.object_transfer_timeline
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
 .. autofunction:: ray.object_transfer_timeline
 
+.. _ray-cluster_resources-ref:
+
+ray.cluster_resources
+~~~~~~~~~~~~~~~~~~~~~
+
 .. autofunction:: ray.cluster_resources
 
+.. _ray-available_resources-ref:
+
+ray.available_resources
+~~~~~~~~~~~~~~~~~~~~~~~
+
 .. autofunction:: ray.available_resources
 
+.. _ray-errors-ref:
+
+ray.errors
+~~~~~~~~~~
+
 .. autofunction:: ray.errors
 
 Experimental APIs

doc/source/ray-overview/index.rst

@@ -85,10 +85,10 @@ Tune Quick Start
 
     .. code-block:: bash
 
-        $ pip install ray torch torchvision filelock
+        $ pip install 'ray[tune]'
 
 
-This example runs a small grid search to train a CNN using PyTorch and Tune.
+This example runs a small grid search with an iterative training function.
 
 .. literalinclude:: ../../../python/ray/tune/tests/example.py
    :language: python

doc/source/serialization.rst

@@ -65,12 +65,7 @@ Serialization notes
 Last resort: Custom Serialization
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-If none of these options work, you can try registering a custom serializer.
-
-.. autofunction:: ray.register_custom_serializer
-  :noindex:
-
-Below is an example of using ``ray.register_custom_serializer``:
+If none of these options work, you can try registering a custom serializer with ``ray.register_custom_serializer`` (:ref:`docstring <ray-register_custom_serializer-ref>`):
 
 .. code-block:: python
 

doc/source/walkthrough.rst

@@ -172,7 +172,7 @@ Further, remote functions can return multiple object refs.
 
   a_id, b_id, c_id = return_multiple.remote()
 
-Remote functions can be canceled by calling ``ray.cancel`` on the returned Object ref. Remote actor functions can be stopped by killing the actor using the ``ray.kill`` interface.
+Remote functions can be canceled by calling ``ray.cancel`` (:ref:`docstring <ray-cancel-ref>`) on the returned Object ref. Remote actor functions can be stopped by killing the actor using the ``ray.kill`` interface.
 
 .. code-block:: python
 
@@ -184,9 +184,6 @@ Remote functions can be canceled by calling ``ray.cancel`` on the returned Objec
   obj_ref = blocking_operation.remote()
   ray.cancel(obj_ref)
 
-.. autofunction:: ray.cancel
-    :noindex:
-
 Objects in Ray
 --------------
 
@@ -199,16 +196,13 @@ similar.
 Object refs can be created in multiple ways.
 
   1. They are returned by remote function calls.
-  2. They are returned by ``ray.put``.
+  2. They are returned by ``ray.put`` (:ref:`docstring <ray-put-ref>`).
 
 .. code-block:: python
 
     y = 1
     object_ref = ray.put(y)
 
-.. autofunction:: ray.put
-    :noindex:
-
 .. note::
 
     Remote objects are immutable. That is, their values cannot be changed after
@@ -219,7 +213,7 @@ Object refs can be created in multiple ways.
 Fetching Results
 ----------------
 
-The command ``ray.get(x_id, timeout=None)`` takes an object ref and creates a Python object
+The command ``ray.get(x_id, timeout=None)`` (:ref:`docstring <ray-get-ref>`) takes an object ref and creates a Python object
 from the corresponding remote object. First, if the current node's object store
 does not contain the object, the object is downloaded. Then, if the object is a `numpy array <https://docs.scipy.org/doc/numpy/reference/generated/numpy.array.html>`__
 or a collection of numpy arrays, the ``get`` call is zero-copy and returns arrays backed by shared object store memory.
@@ -247,21 +241,15 @@ You can also set a timeout to return early from a ``get`` that's blocking for to
     except RayTimeoutError:
         print("`get` timed out.")
 
-.. autofunction:: ray.get
-    :noindex:
-
 
 After launching a number of tasks, you may want to know which ones have
-finished executing. This can be done with ``ray.wait``. The function
+finished executing. This can be done with ``ray.wait`` (:ref:`ray-wait-ref`). The function
 works as follows.
 
 .. code:: python
 
     ready_ids, remaining_ids = ray.wait(object_refs, num_returns=1, timeout=None)
 
-.. autofunction:: ray.wait
-    :noindex:
-
 Object Eviction
 ---------------