Docs: polish sky.Task doc strings. (skypilot-org#1302)

* WIP

* Polish sky.Task doc strings.

* docs: expose Task (a subset of methods); hide Dag.

* Tweak Task method order; in docs display methods by source order.

* CLI docs: tweak order; tweak `spot launch`.

* Address comments.

* Code block formatting.

docs/source/conf.py

@@ -52,6 +52,11 @@
 autosummary_generate = True
 napolean_use_rtype = False
 
+# -- Options for autodoc
+
+# Python methods should be presented in source code order
+autodoc_member_order = 'bysource'
+
 # -- Options for HTML output
 
 html_theme = 'sphinx_book_theme'
@@ -88,5 +93,5 @@
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
-# so a file named "default.css" will overwrite the builtin "default.css".
+# so a file named 'default.css' will overwrite the builtin 'default.css'.
 html_static_path = ['_static']

docs/source/reference/api.rst

@@ -18,7 +18,7 @@ Core API
 -----------
 
 sky.launch
-~~~~~~~~
+~~~~~~~~~~
 
 .. autofunction:: sky.launch
 
@@ -54,18 +54,11 @@ sky.autostop
 
 .. _sky-dag-ref:
 
-Task and DAG
+Task
 -----------------
 
-
-sky.Task
-~~~~~~~~~
-
 .. autoclass:: sky.Task
     :members:
+    :exclude-members: estimate_runtime, get_cloud_to_remote_file_mounts, get_inputs_cloud, get_local_to_remote_file_mounts, set_time_estimator, sync_storage_mounts, to_yaml_config
 
-sky.Dag
-~~~~~~~~~
-
-.. autoclass:: sky.Dag
-    :members:
+    .. automethod:: __init__

docs/source/reference/cli.rst

@@ -1,7 +1,7 @@
 .. _cli:
 
 Command Line Interface
-=============
+==========================
 
 Core CLI
 ---------
@@ -34,24 +34,6 @@ Core CLI
    :prog: sky autostop
    :nested: full
 
-
-Interactive Node CLI
------------------------
-
-.. click:: sky.cli:cpunode
-   :prog: sky cpunode
-   :nested: full
-
-.. _sky-gpunode:
-.. click:: sky.cli:gpunode
-   :prog: sky gpunode
-   :nested: full
-
-.. click:: sky.cli:tpunode
-   :prog: sky tpunode
-   :nested: full
-
-
 Job Queue CLI
 --------------
 
@@ -68,17 +50,6 @@ Job Queue CLI
    :nested: full
 
 
-Storage CLI
-------------
-
-.. click:: sky.cli:storage_ls
-   :prog: sky storage ls
-   :nested: full
-
-.. click:: sky.cli:storage_delete
-   :prog: sky storage delete
-   :nested: full
-
 Managed Spot Jobs CLI
 ---------------------------
 
@@ -98,14 +69,42 @@ Managed Spot Jobs CLI
    :prog: sky spot logs
    :nested: full
 
-Miscellaneous
--------------
+Interactive Node CLI
+-----------------------
 
-.. click:: sky.cli:check
-   :prog: sky check
+.. click:: sky.cli:cpunode
+   :prog: sky cpunode
+   :nested: full
+
+.. _sky-gpunode:
+.. click:: sky.cli:gpunode
+   :prog: sky gpunode
+   :nested: full
+
+.. click:: sky.cli:tpunode
+   :prog: sky tpunode
+   :nested: full
+
+
+Storage CLI
+------------
+
+.. click:: sky.cli:storage_ls
+   :prog: sky storage ls
    :nested: full
 
+.. click:: sky.cli:storage_delete
+   :prog: sky storage delete
+   :nested: full
+
+Utils: ``show-gpus``, ``check``
+---------------------------------------
+
 
 .. click:: sky.cli:show_gpus
    :prog: sky show-gpus
    :nested: full
+
+.. click:: sky.cli:check
+   :prog: sky check
+   :nested: full

sky/cli.py

@@ -2408,10 +2408,15 @@ def check():
 def show_gpus(gpu_name: Optional[str], all: bool, cloud: Optional[str]):  # pylint: disable=redefined-builtin
     """Show supported GPU/TPU/accelerators.
 
+    The names and counts shown can be set in the ``accelerators`` field in task
+    YAMLs, or in the ``--gpus`` flag in CLI commands. For example, if this
+    table shows 8x V100s are supported, then the string ``V100:8`` will be
+    accepted by the above.
+
     To show the detailed information of a GPU/TPU type (which clouds offer it,
     the quantity in each VM type, etc.), use ``sky show-gpus <gpu>``.
 
-    To show all GPUs, including less common ones and their detailed
+    To show all accelerators, including less common ones and their detailed
     information, use ``sky show-gpus --all``.
 
     NOTE: The price displayed for each instance type is the lowest across all
@@ -2738,7 +2743,20 @@ def spot_launch(
     retry_until_up: bool,
     yes: bool,
 ):
-    """Launch a managed spot job."""
+    """Launch a managed spot job from a YAML or a command.
+
+    If ENTRYPOINT points to a valid YAML file, it is read in as the task
+    specification. Otherwise, it is interpreted as a bash command.
+
+    Examples:
+
+    .. code-block:: bash
+
+      # You can use normal task YAMLs.
+      sky spot launch task.yaml
+
+      sky spot launch 'echo hello!'
+    """
     if name is None:
         name = backend_utils.generate_cluster_name()
     else:

sky/execution.py

@@ -299,12 +299,12 @@ def launch(
     (when specified, it is synced to remote cluster).  The task undergoes job
     queue scheduling on the cluster.
 
-    Currently, the first argument must be a sky.Task, or (more advanced usage)
-    a sky.Dag; in the latter case, currently it must be a single task).
-    Support for pipelines/general DAGs are in experimental branches.
+    Currently, the first argument must be a sky.Task, or (EXPERIMENTAL advanced
+    usage) a sky.Dag. In the latter case, currently it must contain a single
+    task; support for pipelines/general DAGs are in experimental branches.
 
     Args:
-        task: sky.Task or sky.Dag to launch.
+        task: sky.Task, or sky.Dag (experimental; 1-task only) to launch.
         cluster_name: name of the cluster to create/reuse.  If None,
             auto-generate a name.
         retry_until_up: whether to retry launching the cluster until it is
@@ -333,15 +333,13 @@ def launch(
         no_setup: if True, do not re-run setup commands.
 
     Example:
-        >>> import sky
-        >>> task = sky.Task(run='echo hello SkyPilot')
-        >>> task.set_resources(
-        ...         sky.Resources(
-        ...             cloud=sky.AWS(),
-        ...             accelerators='V100:4'
-        ...         )
-        ... )
-        >>> sky.launch(task, cluster_name='my-cluster')
+        .. code-block:: python
+
+            import sky
+            task = sky.Task(run='echo hello SkyPilot')
+            task.set_resources(
+                sky.Resources(cloud=sky.AWS(), accelerators='V100:4'))
+            sky.launch(task, cluster_name='my-cluster')
 
     """
     entrypoint = task
@@ -397,7 +395,8 @@ def exec(  # pylint: disable=redefined-builtin
       Use ``ssh my_cluster`` instead.
 
     Args:
-        task: sky.Task or sky.Dag containing the task to execute.
+        task: sky.Task, or sky.Dag (experimental; 1-task only) containing the
+          task to execute.
         cluster_name: name of an existing cluster to execute the task.
         down: Tear down the cluster after all jobs finish (successfully or
             abnormally). If --idle-minutes-to-autostop is also set, the
@@ -460,7 +459,8 @@ def spot_launch(
     Please refer to the sky.cli.spot_launch for the document.
 
     Args:
-        task: sky.Task or sky.Dag to launch as a managed spot job.
+        task: sky.Task, or sky.Dag (experimental; 1-task only) to launch as a
+          managed spot job.
         name: Name of the spot job.
         detach_run: Whether to detach the run.