Touches on docs. (skypilot-org#684)

* Touches on docs.

* Touches

* touches on yaml-spec

* update --gpus=all

* extend underline

Author: concretevitamin

docs/source/examples/iterative-dev-project.rst

@@ -5,17 +5,18 @@ Iteratively Developing a Project
 This page shows a typical workflow for iteratively developing and running a
 project on Sky.
 
-Provisioning a VM
+Getting an interactive node
 ------------------
-To provision a GPU-based :ref:`interactive node <interactive-nodes>` named :code:`dev`, run
+:ref:`Interactive nodes <interactive-nodes>` are easy-to-spin-up VMs that enable **fast development and interactive debugging**.
+
+To provision a GPU interactive node named :code:`dev`, run
 
 .. code-block:: console
 
   $ # Provisions/reuses an interactive node with a single K80 GPU.
   $ sky gpunode -c dev --gpus K80
 
-Interactive nodes are easy-to-spin-up VMs that allow for fast development and interactive debugging.
-See the :ref:`CLI reference <sky-gpunode>` for all configuration options.
+See the :ref:`CLI reference <sky-gpunode>` for all flags such as changing the GPU type and count.
 
 Running code
 --------------------

docs/source/getting-started/installation.rst

@@ -12,6 +12,9 @@ Install Sky using pip:
   $ cd sky
   $ pip install ".[all]"
 
+  $ # To install AWS dependencies only:
+  $ # pip install ".[aws]"
+
 Sky currently supports three major cloud providers: AWS, GCP, and Azure.  If you
 only have access to certain clouds, use any combination of
 :code:`".[aws,azure,gcp]"` (e.g., :code:`".[aws,gcp]"`) to reduce the
@@ -83,3 +86,13 @@ This will produce a summary like:
     Azure: enabled
 
   Sky will use only the enabled clouds to run tasks. To change this, configure cloud credentials, and run sky check.
+
+Requesting quotas for first time users
+--------------------------------------
+
+If your cloud account has not been used to launch instances before, the
+respective quotas are likely set to zero or a low limit.  This is especially
+true for GPU instances.
+
+Please follow :ref:`Requesting Quota Increase` to check quotas and request quota
+increases before proceeding.

docs/source/reference/auto-stop.rst

@@ -2,12 +2,13 @@
 Auto-stopping
 =========
 
-Sky's **auto-stopping** can automatically stop a cluster after a few minutes of idleness.
+Sky's **auto-stopping** automatically stops a cluster after it becomes idle.
+
 With auto-stopping, users can simply submit jobs and leave their laptops, while
 **ensuring no unnecessary spending occurs**: after jobs have finished, the
-cluster(s) used will be automatically stopped (and restarted later).
+cluster(s) used will be automatically stopped (which can be restarted later).
 
-To setup auto-stopping for a cluster, use :code:`sky autostop`:
+To schedule auto-stopping for a cluster, use :code:`sky autostop`:
 
 .. code-block:: bash
 
@@ -40,7 +41,7 @@ To view the status of the cluster, use ``sky status [--refresh]``:
    # Refresh the status for auto-stopping
    sky status --refresh
    NAME         LAUNCHED    RESOURCES            STATUS   AUTOSTOP  COMMAND
-   mycluster    11 min ago  2x AWS(m4.2xlarge)   STOPPED  -         sky launch -d -c ...
+   mycluster    11 min ago  2x AWS(m4.2xlarge)   STOPPED  10 min    sky launch -d -c ...
 
 
 :code:`sky status` shows the cached statuses, which can be outdated for clusters with auto-stopping scheduled. To query the real statuses of clusters with auto-stopping scheduled, use :code:`sky status --refresh`.

docs/source/reference/job-queue.rst

@@ -78,6 +78,22 @@ Use :code:`sky exec mycluster task.yaml` to submit this task, which will be sche
 
 See :ref:`Distributed Jobs on Many VMs` for more details.
 
+Using ``CUDA_VISIBLE_DEVICES``
+--------------------------------
+
+The environment variable ``CUDA_VISIBLE_DEVICES`` will be automatically set to
+the devices allocated to each task on each node. This variable is set
+when a task's ``run`` commands are invoked.
+
+For example, ``task.yaml`` above launches a 4-GPU task on each node that has 8
+GPUs, so the task's ``run`` commands will be invoked with
+``CUDA_VISIBLE_DEVICES`` populated with 4 device IDs.
+
+If your ``run`` commands use Docker/``docker run``, simply pass ``--gpus=all``
+as the correct environment variable is made available to the container (only the
+allocated device IDs will be set).
+
+
 Scheduling behavior
 --------------------------------
 

docs/source/reference/quota.rst

@@ -14,7 +14,7 @@ AWS
 
 1. Go to the `EC2 Quotas console <https://console.aws.amazon.com/servicequotas/home/services/ec2/quotas>`_.
 2. **Select a region** on the top right.
-3. Choose an EC2 instance type from the list (e.g, ``Running On-Demand P instances``). Use ``sky show-gpus --cloud aws --all`` or check `here <https://aws.amazon.com/ec2/instance-types/>`_ for more instance types.
+3. Choose an EC2 instance type from the list (e.g, ``Running On-Demand P instances`` or ``All P Spot Instance Requests``). Use ``sky show-gpus --cloud aws --all`` or check `here <https://aws.amazon.com/ec2/instance-types/>`_ for more instance types.
 4. Click the quota name, and then choose **Request quota increase**.
 5. For **Change quota value**, enter the new value.
 6. Choose **Request**.
@@ -43,4 +43,4 @@ GCP
 3. Choose ``Limit Name: instance_name``. (e.g., ``NVIDIA-V100-GPUS-per-project-region``). You may check `here <https://cloud.google.com/compute/quotas#gpu_quota>`_ for a complete GPU list. 
 4. Select the checkbox of the region whose quota you want to change.
 5. Click **Edit Quotas** and fill out the new limit.
-6. Click **Submit Request**.
+6. Click **Submit Request**.

docs/source/reference/yaml-spec.rst

@@ -8,84 +8,84 @@ describe all fields available.
 
 .. code-block:: yaml
 
-    # Task name (optional), used in the job queue.
+    # Task name (optional), used for display purposes.
     name: my-task
 
     # Working directory (optional), synced to ~/sky_workdir on the remote cluster
     # each time launch or exec is run with the yaml file.
     #
-    # NOTE: Sky does not currently support large, multi-gigabyte workdirs as the
-    # files are synced to the remote VM with `rsync`. Please consider using Sky
-    # Storage to transfer large datasets and files.
+    # Commands in "setup" and "run" will be executed under it.
     #
     # If a .gitignore file (or a .git/info/exclude file) exists in the working
-    # directory, files and directories listed in those files will be ignored.
+    # directory, files and directories listed in it will be excluded from syncing.
     workdir: ~/my-task-code
 
-    # Number of nodes (optional) to launch including the head node. If not
-    # specified, defaults to 1. The specified resource requirements are identical
-    # across all nodes.
+    # Number of nodes (optional; defaults to 1) to launch including the head node.
+    #
+    # A task can set this to a smaller value than the size of a cluster.
     num_nodes: 4
 
     # Per-node resource requirements (optional).
     resources:
-      cloud: aws  # A cloud (optional) can be specified, if desired.
+      cloud: aws  # The cloud to use (optional).
 
-      # Accelerator requirements (optional) can be specified, use `sky show-gpus`
-      # to view available accelerator configurations.
-      # This specifies the accelerator type and the count per node. Format:
-      # <name>:<cnt> or <name> (short for a count of 1).
+      # Accelerator name and count per node (optional).
+      #
+      # Use `sky show-gpus` to view available accelerator configurations.
+      #
+      # Format: <name>:<count> (or simply <name>, short for a count of 1).
       accelerators: V100:4
 
-      # Accelerator arguments (optional) provides additional metadata for some
-      # accelerators, such as the TensorFlow version for TPUs.
-      accelerator_args:
-        tf_version: 2.5.0
+      # Instance type to use (optional). If 'accelerators' is specified,
+      # the corresponding instance type is automatically inferred.
+      instance_type: p3.8xlarge
 
-      # Specify whether the cluster should use spot instances or not (optional).
-      # If unspecified, Sky will default to on-demand instances.
+      # Whether the cluster should use spot instances (optional).
+      # If unspecified, defaults to False (on-demand instances).
       use_spot: False
 
       # Disk size in GB to allocate for OS (mounted at /). Increase this if you
       # have a large working directory or tasks that write out large outputs.
       disk_size: 256
 
-    # Using Sky Storage, you can specify file mounts (all optional).
+      # Additional accelerator metadata (optional); only used for TPUs.
+      accelerator_args:
+        tf_version: 2.5.0
+        tpu_name: mytpu
+
     file_mounts:
-      # This uses rsync to directly copy files from your machine to the remote
-      # VM at /remote/path/datasets. Rsync will copy symlinks as symlinks. The
-      # symlink targets must also be synced using file_mounts to ensure they are
-      # functional.
+      # Uses rsync to copy local files to all nodes of the cluster.
+      #
+      # If symlinks are present, they are copied as symlinks, and their targets
+      # must also be synced using file_mounts to ensure correctness.
       /remote/path/datasets: /local/path/datasets
 
-      # This uses Sky Storage to first create a S3 bucket named sky-dataset,
-      # copies the contents of /local/path/datasets to the remote bucket and makes the
-      # bucket persistent (i.e., the bucket is not deleted after the completion of
-      # this sky task, and future invocations of this bucket will be much faster).
-      # The bucket is mounted at /datasets-storage. Symlink contents are copied over.
+      # Uses Sky Storage to create a S3 bucket named sky-dataset, uploads the
+      # contents of /local/path/datasets to the bucket, and marks the bucket
+      # as persistent (it will not be deleted after the completion of this task).
+      # Symlink contents are copied over.
+      #
+      # Mounts the bucket at /datasets-storage on every node of the cluster.
       /datasets-storage:
         name: sky-dataset
         source: /local/path/datasets
-        force_stores: [s3]  # Could be [s3, gcs], [gcs] default: None
-        persistent: True  # Defaults to True, can be set to false.
+        force_stores: [s3]  # Could be [s3, gcs], [gcs]; default: None
+        persistent: True  # Defaults to True; can be set to false
 
-      # This re-uses a predefined bucket (sky-dataset, defined above) and mounts it
-      # directly at datasets-s3.
-      /datasets-s3: s3://sky-dataset
+      # Copies a cloud object store URI to the cluster. Can be private buckets.
+      /datasets-s3: s3://my-awesome-dataset
 
-    # A setup script (optional) can be provided to run when a cluster is provisioned or a
-    # task is launched. Alternatively, a single setup command can be provided by removing |
-    # and using the following syntax:
-    # setup: pip install -r requirements.txt
+    # Setup script (optional) to execute on every `sky launch`.
+    # This is executed before the 'run' commands.
+    #
+    # The '|' separator indicates a multiline string. To specify a single command:
+    #   setup: pip install -r requirements.txt
     setup: |
       echo "Begin setup."
       pip install -r requirements.txt
       echo "Setup complete."
 
-    # A task script (optional, but recommended) is the main script to run on the
-    # cluster. Alternatively, a single run command can be provided by removing |
-    # and using the following syntax:
-    # run: python train.py
+    # Main program (optional, but recommended) to run on every node of the cluster.
     run: |
       echo "Beginning task."
       python train.py