From 085a6713a0632a3f7427fd500df1d8ccb37d9305 Mon Sep 17 00:00:00 2001
From: Richard Liaw <rliaw@berkeley.edu>
Date: Sun, 27 Oct 2019 17:58:04 -0700
Subject: [PATCH] [docs] Add documentation for Dynamic Custom Resources (#6000)

---
 doc/source/advanced.rst    | 30 ++++++++++++++++++++++++++++++
 doc/source/package-ref.rst |  4 ++++
 2 files changed, 34 insertions(+)

diff --git a/doc/source/advanced.rst b/doc/source/advanced.rst
index 7d54c1e47..c3567ec6b 100644
--- a/doc/source/advanced.rst
+++ b/doc/source/advanced.rst
@@ -51,6 +51,36 @@ And vary the number of return values for tasks (and actor methods too):
     assert ray.get(id1) == 0
     assert ray.get(id2) == 1
 
+Dynamic Custom Resources
+------------------------
+
+Ray enables explicit developer control with respect to the task and actor placement by using custom resources. Further, users are able to dynamically adjust custom resources programmatically with ``ray.experimental.set_resource``. This allows the Ray application to implement virtually any scheduling policy, including task affinity, data locality, anti-affinity,
+load balancing, gang scheduling, and priority-based scheduling.
+
+
+.. code-block:: python
+
+    ray.init()
+    resource_name = "test_resource"
+    resource_capacity = 1.0
+
+    @ray.remote
+    def set_resource(resource_name, resource_capacity):
+        ray.experimental.set_resource(resource_name, resource_capacity)
+
+    ray.get(set_resource.remote(resource_name, resource_capacity))
+
+    available_resources = ray.available_resources()
+    cluster_resources = ray.cluster_resources()
+
+    assert available_resources[resource_name] == resource_capacity
+    assert cluster_resources[resource_name] == resource_capacity
+
+
+.. autofunction:: ray.experimental.set_resource
+    :noindex:
+
+
 
 Nested Remote Functions
 -----------------------
diff --git a/doc/source/package-ref.rst b/doc/source/package-ref.rst
index c88dcd26c..5ec047c14 100644
--- a/doc/source/package-ref.rst
+++ b/doc/source/package-ref.rst
@@ -46,6 +46,10 @@ Inspect the Cluster State
 
 .. autofunction:: ray.errors
 
+Experimental APIs
+-----------------
+
+.. automodule:: ray.experimental
 
 The Ray Command Line API
 ------------------------