Address docs build warnings (#1133)

docs/api/cli.rst

@@ -1,4 +1,3 @@
-.. _cli-reference:
 Command Line Interface
 ------------------------------------
 Runhouse provides CLI commands for logging in/out, and for basic interaction
@@ -12,6 +11,6 @@ The commands can be run like follows:
    $ runhouse ssh cluster_name
 
 .. automodule:: runhouse.main
-   :members: login, logout, ssh, notebook, cancel, logs, start, restart, status
+   :members: login, logout, ssh, notebook, start, restart, status
    :undoc-members:
    :show-inheritance:

docs/api/python.rst

@@ -76,9 +76,9 @@ to other data concepts in the future, like kv-stores, time-series, vector and gr
 Secrets
 ------------------------------------
 Runhouse provides a convenient interface for managing your secrets in a secure manner.
-Secrets are stored in `Vault <https://www.vaultproject.io/>`_, an industry standard for
+Secrets are stored in `Vault <https://www.vaultproject.io/>`__, an industry standard for
 secrets management, and never touches Runhouse servers. Please see
-:ref:`Security and Metadata Collection` for more information on security.
+:ref:`Security and Authentication` for more information on security.
 
 .. toctree::
    :maxdepth: 1

docs/api/python/cluster.rst

@@ -1,8 +1,8 @@
 Cluster
-====================================
+=======
 A Cluster is a Runhouse primitive used for abstracting a particular hardware configuration.
 This can be either an :ref:`on-demand cluster <OnDemandCluster Class>` (requires valid cloud credentials), a
-:ref:`BYO (bring-your-own) cluster <Cluster Factory Method>` (requires IP address and ssh creds), or a
+:ref:`BYO (bring-your-own) cluster <Cluster Class>` (requires IP address and ssh creds), or a
 :ref:`SageMaker cluster <SageMakerCluster Class>` (requires an ARN role).
 
 A cluster is assigned a name, through which it can be accessed and reused later on.
@@ -53,16 +53,16 @@ need to first set up cloud access on your local machine:
 Run ``sky check`` to see which cloud providers are enabled, and how to set up cloud credentials for each of the
 providers.
 
-.. code-block:: cli
+.. code-block::
 
-    sky check
+    $ sky check
 
 For a more in depth tutorial on setting up individual cloud credentials, you can refer to
-`SkyPilot setup docs <https://skypilot.readthedocs.io/en/latest/getting-started/installation.html#cloud-account-setup>`_.
+`SkyPilot setup docs <https://skypilot.readthedocs.io/en/latest/getting-started/installation.html#cloud-account-setup>`__.
 
 
 SageMakerCluster Class
-~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~
 .. note::
 
     SageMaker support is an alpha and under active development. Please report any bugs or let us know of any
@@ -79,7 +79,7 @@ Runhouse currently supports two core usage paths for SageMaker clusters:
 
 - **Dedicated training jobs**: You can use a SageMakerCluster class to run a training job on SageMaker compute.
   To do so, you will need to provide an
-  `estimator <https://sagemaker.readthedocs.io/en/stable/api/training/estimators.html>`_.
+  `estimator <https://sagemaker.readthedocs.io/en/stable/api/training/estimators.html>`__.
 
 .. note::
 
@@ -101,9 +101,9 @@ SageMaker Hardware Setup
 IAM Role
 ^^^^^^^^
 
-SageMaker clusters require `AWS CLI V2 <https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-welcome.html>`_ and
+SageMaker clusters require `AWS CLI V2 <https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-welcome.html>`__ and
 configuring the SageMaker IAM role with the
-`AWS Systems Manager <https://docs.aws.amazon.com/systems-manager/latest/userguide/ssm-agent.html>`_.
+`AWS Systems Manager <https://docs.aws.amazon.com/systems-manager/latest/userguide/ssm-agent.html>`__.
 
 
 In order to launch a cluster, you must grant SageMaker the necessary permissions with an IAM role, which
@@ -119,7 +119,7 @@ For example, let's say your local :code:`~/.aws/config` file contains:
     region = us-east-1
     source_profile = default
 
-There are several ways to provide the necessary credentials when :ref:`initializing the cluster <SageMaker Factory Method>`:
+There are several ways to provide the necessary credentials when :ref:`initializing the cluster <Cluster Factory Methods>`:
 
 - Providing the AWS profile name: :code:`profile="sagemaker"`
 - Providing the AWS Role ARN directly: :code:`role="arn:aws:iam::123456789:role/service-role/AmazonSageMaker-ExecutionRole-20230717T192142"`
@@ -133,9 +133,9 @@ There are several ways to provide the necessary credentials when :ref:`initializ
 .. tip::
 
     If you are providing an estimator, you must provide the role ARN explicitly as part of the estimator object.
-    More info on estimators `here <https://sagemaker.readthedocs.io/en/stable/api/training/estimators.html>`_.
+    More info on estimators `here <https://sagemaker.readthedocs.io/en/stable/api/training/estimators.html>`__.
 
-Please see the `AWS docs <https://docs.aws.amazon.com/sagemaker/latest/dg/sagemaker-roles.html>`_ for further
+Please see the `AWS docs <https://docs.aws.amazon.com/sagemaker/latest/dg/sagemaker-roles.html>`__ for further
 instructions on creating and configuring an ARN Role.
 
 
@@ -151,9 +151,9 @@ The SageMaker SDK uses AWS CLI V2, which must be installed on your local machine
 
 To confirm the installation succeeded, run ``aws --version`` in the command line. You should see something like:
 
-.. code-block:: cli
+.. code-block::
 
-    aws-cli/2.13.8 Python/3.11.4 Darwin/21.3.0 source/arm64 prompt/off
+    $ aws-cli/2.13.8 Python/3.11.4 Darwin/21.3.0 source/arm64 prompt/off
 
 If you are still seeing the V1 version, first try uninstalling V1 in case it is still present
 (e.g. ``pip uninstall awscli``).
@@ -165,35 +165,35 @@ else (e.g. ``/opt/homebrew/bin/aws``).
 
 To find the global AWS CLI path:
 
-.. code-block:: cli
+.. code-block::
 
-    which aws
+    $ which aws
 
 To ensure that the global AWS CLI version is used within your python environment, you’ll need to adjust the
 PATH environment variable so that it prioritizes the global AWS CLI path.
 
-.. code-block:: cli
+.. code-block::
 
-    export PATH=/opt/homebrew/bin:$PATH
+    $ export PATH=/opt/homebrew/bin:$PATH
 
 
 SSM Setup
 ^^^^^^^^^
 The AWS Systems Manager service is used to create SSH tunnels with the SageMaker cluster.
 
 To install the AWS Session Manager Plugin, please see the `AWS docs <https://docs.aws.amazon.com/systems-manager/latest/userguide/session-manager-working-with-install-plugin.html>`_
-or `SageMaker SSH Helper <https://github.com/aws-samples/sagemaker-ssh-helper#step-4-connect-over-ssm>`_. The SSH Helper package
+or `SageMaker SSH Helper <https://github.com/aws-samples/sagemaker-ssh-helper#step-4-connect-over-ssm>`__. The SSH Helper package
 simplifies the process of creating SSH tunnels with SageMaker clusters. It is installed by default if
 you are installing Runhouse with the SageMaker dependency: :code:`pip install runhouse[sagemaker]`.
 
 You can also install the Session Manager by running the CLI command:
 
-.. code-block:: cli
+.. code-block::
 
-    sm-local-configure
+    $ sm-local-configure
 
 To configure your SageMaker IAM role with the AWS Systems Manager, please
-refer to `these instructions <https://github.com/aws-samples/sagemaker-ssh-helper/blob/main/IAM_SSM_Setup.md>`_.
+refer to `these instructions <https://github.com/aws-samples/sagemaker-ssh-helper/blob/main/IAM_SSM_Setup.md>`__.
 
 
 Cluster Authentication & Verification
@@ -204,7 +204,7 @@ Server Connection
 -----------------
 
 The below options can be specified with the ``server_connection_type`` parameter
-when :ref:`initializing a cluster <Cluster Factory Method>`. By default the Runhouse API server will
+when :ref:`initializing a cluster <Cluster Factory Methods>`. By default the Runhouse API server will
 be started on the cluster on port :code:`32300`.
 
 - ``ssh``: Connects to the cluster via an SSH tunnel, by default on port :code:`32300`.
@@ -215,7 +215,7 @@ be started on the cluster on port :code:`32300`.
   default on port :code:`80`. This is useful when connecting to a cluster within a VPC, or creating a tunnel manually
   on the side with custom settings.
 - ``aws_ssm``: Uses the
-  `AWS Systems Manager <https://docs.aws.amazon.com/systems-manager/latest/userguide/what-is-systems-manager.html>`_ to
+  `AWS Systems Manager <https://docs.aws.amazon.com/systems-manager/latest/userguide/what-is-systems-manager.html>`__ to
   create an SSH tunnel to the cluster, by default on port :code:`32300`. *Note: this is currently only relevant
   for SageMaker Clusters.*
 
@@ -235,7 +235,7 @@ has ports open to the public internet, as would usually be the case when using t
 also set up your own authentication manually inside of your own code, but you should likely still enable Runhouse
 authentication to ensure that even your non-user-facing endpoints into the server are secured.
 
-When :ref:`initializing a cluster <Cluster Factory Method>`, you can set the :code:`den_auth` parameter to :code:`True`
+When :ref:`initializing a cluster <Cluster Factory Methods>`, you can set the :code:`den_auth` parameter to :code:`True`
 to enable token authentication. Calls to the cluster server can then be made using an auth header with the
 format: :code:`{"Authorization": "Bearer <cluster-token>"}`. The Runhouse Python library adds this header to its calls
 automatically, so your users do not need to worry about it after logging into Runhouse.
@@ -244,12 +244,12 @@ automatically, so your users do not need to worry about it after logging into Ru
 .. note::
 
    Runhouse never uses your default Runhouse token for anything other than requests made to
-   `Runhouse Den <https://www.run.house/dashboard>`_. Your token will never be exposed or shared with anyone else.
+   `Runhouse Den <https://www.run.house/dashboard>`__. Your token will never be exposed or shared with anyone else.
 
 
 TLS Certificates
 ^^^^^^^^^^^^^^^^
-Enabling TLS and `Runhouse Den Dashboard <https://www.run.house/dashboard>`_ Auth for the API server makes it incredibly
+Enabling TLS and `Runhouse Den Dashboard <https://www.run.house/dashboard>`__ Auth for the API server makes it incredibly
 fast and easy to stand up a microservice with standard token authentication, allowing you to easily share Runhouse
 resources with collaborators, teams, customers, etc.
 
@@ -290,15 +290,15 @@ We can also call the function via an HTTP request, making it easy for other user
 a Runhouse cluster token (Note: this assumes the user has been granted access to the function or
 write access to the cluster):
 
-.. code-block:: cli
+.. code-block::
 
-    curl -X GET "https://<DOMAIN>/concat/call?a=run&b=house"
+    $ curl -X GET "https://<DOMAIN>/concat/call?a=run&b=house"
     -H "Content-Type: application/json" -H "Authorization: Bearer <CLUSTER-TOKEN>"
 
 Caddy
 ^^^^^
-Runhouse gives you the option of using `Caddy <https://caddyserver.com/>`_ as a reverse proxy for the Runhouse API
-server, which is a FastAPI app launched with `Uvicorn <https://www.uvicorn.org/>`_. Using Caddy provides you with a
+Runhouse gives you the option of using `Caddy <https://caddyserver.com/>`__ as a reverse proxy for the Runhouse API
+server, which is a FastAPI app launched with `Uvicorn <https://www.uvicorn.org/>`__. Using Caddy provides you with a
 safer and more conventional approach running the FastAPI app on a higher, non-privileged port (such as 32300, the
 default Runhouse port) and then use Caddy as a reverse proxy to forward requests from the HTTP port (default: 80) or
 the HTTPS port (default: 443).
@@ -343,7 +343,7 @@ before launching the cluster by specifying the :code:`domain` argument:
 
     You'll need to also ensure the relevant ports are open (ex: 443) in the security group settings of the cluster.
     Runhouse will also automatically set up a TLS certificate for the domain via
-    `Caddy <https://caddyserver.com/docs/automatic-https>`_.
+    `Caddy <https://caddyserver.com/docs/automatic-https>`__.
 
 If you have an existing cluster, you can also configure a domain by including the IP and domain when
 initializing the Runhouse cluster object:
@@ -360,7 +360,7 @@ Now we can send modules or functions to our cluster and seamlessly create endpoi
 and call from anywhere.
 
 Let's take a look at an example of how to deploy a simple
-`LangChain RAG app <https://www.run.house/examples/langchain-rag-app-aws-ec2>`_.
+`LangChain RAG app <https://www.run.house/examples/langchain-rag-app-aws-ec2>`__.
 
 Once the app has been created and sent to the cluster, we can call it via HTTP directly:
 
@@ -374,6 +374,6 @@ Once the app has been created and sent to the cluster, we can call it via HTTP d
 
 Or via cURL:
 
-.. code-block:: cli
+.. code-block::
 
-     curl "https://<domain>/basic_rag_app/invoke?user_prompt=<prompt>"
+    $ curl "https://<domain>/basic_rag_app/invoke?user_prompt=<prompt>"

docs/api/python/function.rst

@@ -29,13 +29,14 @@ Lambda Function Class
     Lambda Function support is an alpha and under active development.
     Please report any bugs and let us know of any feature requests.
 
-| A `Lambda Function <https://aws.amazon.com/lambda/>`_ is a serverless compute service provided by AWS. It allows  you
+| A `Lambda Function <https://aws.amazon.com/lambda/>`__ is a serverless compute service provided by AWS. It allows  you
  to run applications and backend services without provisioning or managing servers. Runhouse will allow you to
  maintain, invoke and share your Lambda functions and their code. It is comprised of the entry point, configuration, and
  dependencies necessary to run the service.
 
 
 | There are few core options to create an AWS Lambda using Runhouse:
+
 #. Pass a callable Python function to the factory method.
 #. Follow a typical Lambda creation flow (as if you are using AWS APIs). That includes passing path(s) to Python files(s)
    (containing the code) and a handler function name to the from_handler_file() method. Arguments such as runtime,

docs/architecture.rst

@@ -65,8 +65,6 @@ annotated code snippet:
     # [6]
     gpu.teardown()
 
-.. note::
-
 
 1. Specify and/or Allocate Compute
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -75,8 +73,6 @@ annotated code snippet:
 
     gpu = rh.cluster(name="rh-a10x", instance_type="A10G:1", provider="aws").up_if_not()
 
-.. note::
-
 Runhouse can allocate compute to the application on the fly, either by
 utilizing an existing VM or Ray cluster, or allocating a new one using local cloud or K8s credentials. The
 ``rh.cluster`` constructor is generally used to specify and interact with remote compute, including bringing it up
@@ -111,8 +107,6 @@ installed before starting the daemon.
     sd_worker = rh.env(reqs=["torch", "transformers", "diffusers"], name="sd_generate")
     remote_sd_generate = rh.function(sd_generate).to(gpu, env=sd_worker)
 
-.. note::
-
 The user specifies a function or class to be deployed to the remote compute
 using the ``rh.function`` or ``rh.module`` constructors (or by subclassing ``rh.Module``), and calling
 ``remote_obj = my_obj.to(my_cluster, env=my_env)``. The Runhouse client library extracts the path, module name,
@@ -127,8 +121,6 @@ construct the function or class in a particular worker and upserts it into the k
     imgs = remote_sd_generate("A hot dog made out of matcha.")
     imgs[0].show()
 
-.. note::
-
 After deploying the function, class, or object into the server, the Runhouse
 Python client returns a local callable stub which behaves like the original object but forwards method calls
 over HTTP to the remote object on the cluster.
@@ -152,8 +144,6 @@ over HTTP to the remote object on the cluster.
     sd_upsampler = rh.function(name="/my_username/sd_upsampler")
     high_res_imgs = sd_upsampler(imgs)
 
-.. note::
-
 The Runhouse client can save and load objects to and from the local filesystem, or to a
 remote metadata store. This allows for easy sharing of clusters and services across users and environments,
 and for versioning and rollback of objects. The metadata store can be accessed from any Python interpreter,
@@ -165,8 +155,6 @@ and is backed by UIs and APIs to view, monitor, and manage all resources.
 
     gpu.teardown()
 
-.. note::
-
 When a remote object is no longer needed, it can be deallocated from
 the remote compute by calling ``cluster.delete(obj_name)``. This will remove the object from the key-value store and
 free up the memory on the worker. A worker process can similarly be terminated with ``cluster.delete(worker_name)``,
@@ -195,7 +183,7 @@ more than one cluster in an application or sharing a cluster between multiple ca
 remote compute are largely decoupled, with no shared runtime which will break if one disconnects or goes down.
 
 Workflow orchestrators (e.g. Airflow, Prefect, Dagster, Flyte, Metaflow, Argo)
-^^^^^^^^^^^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 Workflow orchestrators can allocate heterogeneous compute
 on the the fly but act as the runtime itself for the program and only support certain pre-defined and highly
 constrained DAGs. By allocating services Runhouse allows for arbitrary control flow and utilization of remote
@@ -238,7 +226,7 @@ Saving, Loading, and Sharing
 Runhouse resources (clusters, functions, modules, environments) can be saved, shared, and reused based on a compact
 JSON metadata signature. This allows for easy sharing of clusters and services across users and environments, which
 can often lead to massive cost savings. Runhouse comes with a built-in metadata store / service registry called
-`Den <https://www.run.house/dashboard>`_ to facilitate convenient saving, loading, sharing, and management of these
+`Den <https://www.run.house/dashboard>`__ to facilitate convenient saving, loading, sharing, and management of these
 resources. Den can be accessed via an HTTP API or from any Python interpreter with a Runhouse token
 (either in ``~/.rh/config.yaml`` or an ``RH_TOKEN`` environment variable) like so:
 
@@ -258,7 +246,5 @@ resources. Den can be accessed via an HTTP API or from any Python interpreter wi
     # Share the function with another user, giving them access to call or modify the resource
     remote_func.share("user_a@gmail.com", access_level="write")
 
-.. note::
-
 You can access the metadata directly by calling ``resource.config()`` and reconstruct the resource with
 ``<Resource Type>.from_config(config)``.

docs/debugging-logging.rst

@@ -44,4 +44,4 @@ For debugging remote functions, which are launched using ``ray``, we can utilize
 ``breakpoint()`` call inside the function where you want to start the debugging session, then ssh into the
 cluster with ``ssh cluster-name``, and call ``ray debug`` to view select the breakpoint to enter. You can run
 normal ``pdb`` commands within the debugging session, and can refer to
-`Ray Debugger <https://docs.ray.io/en/latest/ray-contribute/debugging.html>`_ for more information.
+`Ray Debugger <https://docs.ray.io/en/latest/ray-contribute/debugging.html>`__ for more information.

docs/docker-setup.rst

@@ -65,11 +65,11 @@ For instance, to use the PyTorch2.2 ECR Framework provided
 you must first set your environment variables somewhere your program can
 access.
 
-.. code:: cli
+.. code::
 
-   export SKYPILOT_DOCKER_USERNAME=AWS
-   export SKYPILOT_DOCKER_PASSWORD=$(aws ecr get-login-password --region us-east-1)
-   export SKYPILOT_DOCKER_SERVER=763104351884.dkr.ecr.us-east-1.amazonaws.com
+   $ export SKYPILOT_DOCKER_USERNAME=AWS
+   $ export SKYPILOT_DOCKER_PASSWORD=$(aws ecr get-login-password --region us-east-1)
+   $ export SKYPILOT_DOCKER_SERVER=763104351884.dkr.ecr.us-east-1.amazonaws.com
 
 Then, instantiate the on-demand cluster and fill in the ``image_id``
 field.

docs/index.rst

@@ -1,7 +1,7 @@
 .. runhouse documentation master file, created by
 
 🏃‍♀️ Runhouse Docs 🏠
-==================
+======================
 
 .. raw:: html