[Docs] Fix docstring examples with mocked outputs (ray-project#35928)

We previously mocked outputs by using the SKIP option flag. The problem with this option is that it skips the code as well as the output. To address this problem, I've introduced MOCK option flag (ray-project/pytest-sphinx#1). This PR updates our documentation accordingly. --------- Signed-off-by: Balaji Veeramani <[email protected]>
charleslai2000 · Jun 1, 2023 · 2f5eda9 · 2f5eda9
1 parent 8d11931
commit 2f5eda9
Show file tree

Hide file tree

Showing 12 changed files with 27 additions and 30 deletions.
diff --git a/doc/source/ray-contribute/writing-code-snippets.rst b/doc/source/ray-contribute/writing-code-snippets.rst
@@ -269,15 +269,15 @@ the `testoutput` directive and replace problematic sections with ellipsis. ::
  )
 
 If your output is nondeterministic and you want to display a sample output, add
-`:options: +SKIP`. ::
+`:options: +MOCK`. ::
 
  .. testcode::
 
  import random
  print(random.random())
 
  .. testoutput::
- :options: +SKIP
+ :options: +MOCK
 
  0.969461416250246
 

diff --git a/doc/source/ray-core/actors.rst b/doc/source/ray-core/actors.rst
@@ -332,7 +332,7 @@ If we instantiate an actor, we can pass the handle around to various tasks.
  print(ray.get(counter.get_counter.remote()))
 
  .. testoutput::
- :options: +SKIP
+ :options: +MOCK
 
  0
  3

diff --git a/doc/source/ray-core/actors/async_api.rst b/doc/source/ray-core/actors/async_api.rst
@@ -50,7 +50,7 @@ async frameworks like aiohttp, aioredis, etc.
  asyncio.run(async_get())
 
 .. testoutput::
- :options: +SKIP
+ :options: +MOCK
 
  (AsyncActor pid=40293) started
  (AsyncActor pid=40293) started
@@ -162,7 +162,7 @@ By using `async` method definitions, Ray will automatically detect whether an ac
  ray.get([actor.run_task.remote() for _ in range(5)])
 
 .. testoutput::
- :options: +SKIP
+ :options: +MOCK
 
  (AsyncActor pid=3456) started
  (AsyncActor pid=3456) started
@@ -205,7 +205,7 @@ You can set the number of "concurrent" task running at once using the
  ray.get([actor.run_task.remote() for _ in range(8)])
 
 .. testoutput::
- :options: +SKIP
+ :options: +MOCK
 
  (AsyncActor pid=5859) started
  (AsyncActor pid=5859) started
@@ -252,7 +252,7 @@ Instead, you can use the ``max_concurrency`` Actor options without any async met
  ray.get([a.task_1.remote(), a.task_2.remote()])
 
 .. testoutput::
- :options: +SKIP
+ :options: +MOCK
 
  (ThreadedActor pid=4822) I'm running in a thread!
  (ThreadedActor pid=4822) I'm running in another thread!

diff --git a/doc/source/ray-core/handling-dependencies.rst b/doc/source/ray-core/handling-dependencies.rst
@@ -775,7 +775,7 @@ Example log output:
  ray.init(runtime_env={"pip": ["requests"]})
 
 .. testoutput::
- :options: +SKIP
+ :options: +MOCK
 
  (pid=runtime_env) 2022-02-28 14:12:33,653 INFO pip.py:188 -- Creating virtualenv at /tmp/ray/session_2022-02-28_14-12-29_909064_87908/runtime_resources/pip/0cc818a054853c3841171109300436cad4dcf594/virtualenv, current python dir /Users/user/anaconda3/envs/ray-py38
  (pid=runtime_env) 2022-02-28 14:12:33,653 INFO utils.py:76 -- Run cmd[1] ['/Users/user/anaconda3/envs/ray-py38/bin/python', '-m', 'virtualenv', '--app-data', '/tmp/ray/session_2022-02-28_14-12-29_909064_87908/runtime_resources/pip/0cc818a054853c3841171109300436cad4dcf594/virtualenv_app_data', '--reset-app-data', '--no-periodic-update', '--system-site-packages', '--no-download', '/tmp/ray/session_2022-02-28_14-12-29_909064_87908/runtime_resources/pip/0cc818a054853c3841171109300436cad4dcf594/virtualenv']

diff --git a/doc/source/ray-core/miscellaneous.rst b/doc/source/ray-core/miscellaneous.rst
@@ -176,7 +176,7 @@ To get information about the current nodes in your cluster, you can use ``ray.no
  print(ray.nodes())
 
 .. testoutput::
- :options: +SKIP
+ :options: +MOCK
 
  [{'NodeID': '2691a0c1aed6f45e262b2372baf58871734332d7',
  'Alive': True,

diff --git a/doc/source/ray-core/objects/serialization.rst b/doc/source/ray-core/objects/serialization.rst
@@ -207,7 +207,7 @@ Below, we demonstrate this behavior on a function with a non-serializable object
 The resulting output is:
 
 .. testoutput::
- :options: +SKIP
+ :options: +MOCK
 
  =============================================================
  Checking Serializability of <function test at 0x7ff130697e50>
@@ -239,4 +239,3 @@ Known Issues
 Users could experience memory leak when using certain python3.8 & 3.9 versions. This is due to `a bug in python's pickle module <https://bugs.python.org/issue39492>`_.
 
 This issue has been solved for Python 3.8.2rc1, Python 3.9.0 alpha 4 or late versions.
-
diff --git a/doc/source/ray-core/tips-for-first-time.rst b/doc/source/ray-core/tips-for-first-time.rst
@@ -72,7 +72,7 @@ Unfortunately, it is quite natural for a new Ray user to inadvertently use ``ray
 The output of a program execution is below. As expected, the program takes around 4 seconds:
 
 .. testoutput::
- :options: +SKIP
+ :options: +MOCK
 
  duration = 4.0149290561676025
  results = [0, 1, 2, 3]
@@ -99,7 +99,7 @@ Now, let’s parallelize the above program with Ray. Some first-time users will
 However, when executing the above program one gets:
 
 .. testoutput::
- :options: +SKIP
+ :options: +MOCK
 
  duration = 0.0003619194030761719
  results = [ObjectRef(df5a1a828c9685d3ffffffff0100000001000000), ObjectRef(cb230a572350ff44ffffffff0100000001000000), ObjectRef(7bbd90284b71e599ffffffff0100000001000000), ObjectRef(bd37d2621480fc7dffffffff0100000001000000)]
@@ -115,7 +115,7 @@ To get the actual results, we need to use ray.get(), and here the first instinc
 By re-running the program after this change we get:
 
 .. testoutput::
- :options: +SKIP
+ :options: +MOCK
 
  duration = 4.018050909042358
  results = [0, 1, 2, 3]
@@ -131,7 +131,7 @@ To enable parallelism, we need to call ``ray.get()`` after invoking all tasks. W
 By re-running the program after this change we now get:
 
 .. testoutput::
- :options: +SKIP
+ :options: +MOCK
 
  duration = 1.0064549446105957
  results = [0, 1, 2, 3]
@@ -162,7 +162,7 @@ Let’s consider again the above examples, but this time we make the tasks much
 By running this program we get:
 
 .. testoutput::
- :options: +SKIP
+ :options: +MOCK
 
  duration = 13.36544418334961
 
@@ -188,7 +188,7 @@ Let’s now parallelize this code using Ray, by making every invocation of ``tin
 The result of running this code is:
 
 .. testoutput::
- :options: +SKIP
+ :options: +MOCK
 
  duration = 27.46447515487671
 
@@ -218,7 +218,7 @@ One way to speed up this program is to make the remote tasks larger in order to
 Now, if we run the above program we get:
 
 .. testoutput::
- :options: +SKIP
+ :options: +MOCK
 
  duration = 3.2539820671081543
 
@@ -238,7 +238,7 @@ This is approximately one fourth of the sequential execution, in line with our e
 Running the above program on a 2018 MacBook Pro notebook shows:
 
 .. testoutput::
- :options: +SKIP
+ :options: +MOCK
 
  per task overhead (ms) = 0.4739549160003662
 
@@ -270,7 +270,7 @@ However, there are cases when automatically calling ``ray.put()`` on a task invo
 This program outputs:
 
 .. testoutput::
- :options: +SKIP
+ :options: +MOCK
 
  duration = 1.0837509632110596
 
@@ -300,7 +300,7 @@ To avoid copying array ``a`` every time ``no_work()`` is invoked, one simple sol
 Running this program takes only:
 
 .. testoutput::
- :options: +SKIP
+ :options: +MOCK
 
  duration = 0.132796049118042
 
@@ -342,7 +342,7 @@ To illustrate this issue, consider the following example where we run four ``do_
 The output of the program shows that it takes close to 8 sec to run:
 
 .. testoutput::
- :options: +SKIP
+ :options: +MOCK
 
  duration = 7.82636022567749
  result = 6
@@ -376,7 +376,7 @@ Fortunately, Ray allows you to do exactly this by calling ``ray.wait()`` on a li
 This program now takes just a bit over 4.8sec, a significant improvement:
 
 .. testoutput::
- :options: +SKIP
+ :options: +MOCK
 
  duration = 4.852453231811523
  result = 6
@@ -386,4 +386,3 @@ To aid the intuition, Figure 1 shows the execution timeline in both cases: when
 .. figure:: /images/pipeline.png
 
  Figure 1: (a) Execution timeline when using ray.get() to wait for all results from ``do_some_work()`` tasks before calling ``process_results()``. (b) Execution timeline when using ``ray.wait()`` to process results as soon as they become available.
-
diff --git a/doc/source/ray-observability/user-guides/debug-apps/debug-other.rst b/doc/source/ray-observability/user-guides/debug-apps/debug-other.rst
@@ -120,7 +120,7 @@ of Ray Tasks itself, e.g.
 This will error with message:
 
 .. testoutput::
- :options: +SKIP
+ :options: +MOCK
 
  ValueError: Cannot schedule create_task_that_uses_resources.<locals>.sample_task with the placement group
  because the resource request {'CPU': 10} cannot fit into any bundles for the placement group, [{'CPU': 1.0}].

diff --git a/python/ray/runtime_context.py b/python/ray/runtime_context.py
@@ -179,7 +179,7 @@ def get_task_id():
  print(ray.get(get_task_id.remote()))
 
  .. testoutput::
- :options: +SKIP
+ :options: +MOCK
 
  16310a0f0a45af5c2746a0e6efb235c0962896a201000000
  c2668a65bda616c1ffffffffffffffffffffffff01000000

diff --git a/python/ray/tune/callback.py b/python/ray/tune/callback.py
@@ -107,7 +107,6 @@ def train(config):
 
  .. testoutput::
  :hide:
- :options: +SKIP
 
  ...
  """

diff --git a/python/ray/util/actor_pool.py b/python/ray/util/actor_pool.py
@@ -141,7 +141,7 @@ def double(self, v):
  [1, 2, 3, 4])))
 
  .. testoutput::
- :options: +SKIP
+ :options: +MOCK
 
  [6, 8, 4, 2]
  """
@@ -332,7 +332,7 @@ def double(self, v):
  print(pool.get_next_unordered())
 
  .. testoutput::
- :options: +SKIP
+ :options: +MOCK
 
  4
  2

diff --git a/python/ray/util/state/api.py b/python/ray/util/state/api.py
@@ -1211,7 +1211,7 @@ def get_log(
  print(l)
 
  .. testoutput::
- :options: +SKIP
+ :options: +MOCK
 
  [2023-05-19 12:35:18,347 I 4259 68399276] (raylet) io_service_pool.cc:35: IOServicePool is running with 1 io_service.
  [2023-05-19 12:35:18,348 I 4259 68399276] (raylet) store_runner.cc:32: Allowing the Plasma store to use up to 2.14748GB of memory.