From 45d0e70142ee0d72462dc258955adb959490e0eb Mon Sep 17 00:00:00 2001
From: Tristan Rice <rice@fn.lc>
Date: Tue, 25 Jan 2022 14:56:52 -0800
Subject: [PATCH] docs/schedulers: add runopts to documentation

---
 docs/source/conf.py                       |  1 +
 docs/source/ext/compatibility.py          | 19 ------------
 docs/source/ext/runopts.py                | 38 +++++++++++++++++++++++
 torchx/schedulers/kubernetes_scheduler.py |  7 +++++
 torchx/schedulers/local_scheduler.py      | 12 +++++--
 torchx/schedulers/slurm_scheduler.py      |  8 +++++
 6 files changed, 63 insertions(+), 22 deletions(-)
 create mode 100644 docs/source/ext/runopts.py

diff --git a/docs/source/conf.py b/docs/source/conf.py
index 737dc58f6..6e6cd658c 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -61,6 +61,7 @@
     "sphinx.ext.autosectionlabel",
     "sphinx_gallery.gen_gallery",
     "compatibility",
+    "runopts",
     "nbsphinx",
     "IPython.sphinxext.ipython_console_highlighting",
 ]
diff --git a/docs/source/ext/compatibility.py b/docs/source/ext/compatibility.py
index cb329fcfd..7633c0c32 100644
--- a/docs/source/ext/compatibility.py
+++ b/docs/source/ext/compatibility.py
@@ -25,25 +25,6 @@ class CompatibilityDirective(SphinxDirective):
     has_content = True
 
     def run(self):
-        """
-        targetid = "todo-%d" % self.env.new_serialno("todo")
-        targetnode = nodes.target("", "", ids=[targetid])
-        todo_node = todo("\n".join(self.content))
-        todo_node += nodes.title(_("Todo"), _("Todo"))
-        self.state.nested_parse(self.content, self.content_offset, todo_node)
-        if not hasattr(self.env, "todo_all_todos"):
-            self.env.todo_all_todos = []
-
-        self.env.todo_all_todos.append(
-            {
-                "docname": self.env.docname,
-                "lineno": self.lineno,
-                "todo": todo_node.deepcopy(),
-                "target": targetnode,
-            }
-        )
-        """
-
         raw_content = "\n".join(self.content)
         args = yaml.safe_load(raw_content)
         fields = COMPATIBILITY_SETS[args["type"]]
diff --git a/docs/source/ext/runopts.py b/docs/source/ext/runopts.py
new file mode 100644
index 000000000..3eec5df7a
--- /dev/null
+++ b/docs/source/ext/runopts.py
@@ -0,0 +1,38 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+from pydoc import locate
+
+import yaml
+from docutils import nodes
+from sphinx.util.docutils import SphinxDirective
+
+
+class RunOptsDirective(SphinxDirective):
+    # this enables content in the directive
+    has_content = True
+
+    def run(self):
+        raw_content = "\n".join(self.content)
+        args = yaml.safe_load(raw_content)
+        cls = locate(args["class"])
+
+        body = nodes.literal_block(text=str(cls.run_opts(None)))
+        return [
+            body,
+        ]
+
+
+def setup(app):
+    app.add_directive("runopts", RunOptsDirective)
+
+    return {
+        "version": "0.1",
+        "parallel_read_safe": True,
+        "parallel_write_safe": True,
+    }
diff --git a/torchx/schedulers/kubernetes_scheduler.py b/torchx/schedulers/kubernetes_scheduler.py
index b2da1d474..09a5a02ff 100644
--- a/torchx/schedulers/kubernetes_scheduler.py
+++ b/torchx/schedulers/kubernetes_scheduler.py
@@ -331,6 +331,13 @@ class KubernetesScheduler(Scheduler):
         $ torchx status kubernetes://torchx_user/1234
         ...
 
+    **Config Options**
+
+    .. runopts::
+        class: torchx.schedulers.kubernetes_scheduler.KubernetesScheduler
+
+    **Compatibility**
+
     .. compatibility::
         type: scheduler
         features:
diff --git a/torchx/schedulers/local_scheduler.py b/torchx/schedulers/local_scheduler.py
index feaedf40a..0d4b21313 100644
--- a/torchx/schedulers/local_scheduler.py
+++ b/torchx/schedulers/local_scheduler.py
@@ -528,10 +528,16 @@ class LocalScheduler(Scheduler):
     .. note::
         The orphan cleanup only works if `LocalScheduler` is instantiated from the main thread.
 
+    **Config Options**
+
+    .. runopts::
+        class: torchx.schedulers.local_scheduler.LocalScheduler
+
+    **Compatibility**
+
     .. note::
-        Use this scheduler sparingly since an application that runs successfully
-        on a session backed by this scheduler may not work on an actual
-        production cluster using a different scheduler.
+        Due to scheduler differences jobs that run locally may not work when
+        using a different scheduler due to network or software dependencies.
 
     .. compatibility::
         type: scheduler
diff --git a/torchx/schedulers/slurm_scheduler.py b/torchx/schedulers/slurm_scheduler.py
index 7c3dbf1f8..8af98ac98 100644
--- a/torchx/schedulers/slurm_scheduler.py
+++ b/torchx/schedulers/slurm_scheduler.py
@@ -199,6 +199,13 @@ class SlurmScheduler(Scheduler):
         $ less slurm-1234.out
         ...
 
+    **Config Options**
+
+    .. runopts::
+        class: torchx.schedulers.slurm_scheduler.SlurmScheduler
+
+    **Compatibility**
+
     .. compatibility::
         type: scheduler
         features:
@@ -210,6 +217,7 @@ class SlurmScheduler(Scheduler):
             describe: |
                 Partial support. SlurmScheduler will return job and replica
                 status but does not provide the complete original AppSpec.
+
     """
 
     def __init__(self, session_name: str) -> None: