[docs] Add documentation for Dynamic Custom Resources (#6000)

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
 -----------------------

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
 ------------------------