Introduce lightning connect

docs/source-app/glossary/command_lines/command_lines.rst

@@ -0,0 +1,76 @@
+:orphan:
+
+############################
+Command-line Interface (CLI)
+############################
+
+**Audience:** Users looking to create a command line interface (CLI) for their application.
+
+----
+
+**************
+What is a CLI?
+**************
+
+A Command-line Interface (CLI) is an user interface (UI) in a terminal to interact with a specific program.
+
+.. note::
+
+    The Lightning guideline to build CLI is `lightning <VERB> <NOUN> ...` or `<ACTION> <OBJECT> ...`.
+
+As an example, Lightning provides a CLI to interact with your Lightning Apps and the `lightning.ai <https://lightning.ai/>`_ platform as follows:
+
+.. code-block:: bash
+
+    main
+    ├── create - Creates Lightning AI self-managed resources (clusters, etc…)
+    │   └── cluster - Creates a Lightning AI BYOC compute cluster with your cloud provider credentials.
+    ├── delete - Deletes Lightning AI self-managed resources (clusters, etc…)
+    │   └── cluster - Deletes a Lightning AI BYOC compute cluster and all associated cloud provider resources.
+    ├── fork - Forks an App.
+    ├── init - Initializes a Lightning App and/or Component.
+    │   ├── app
+    │   ├── component
+    │   ├── pl-app - Creates an App from your PyTorch Lightning source files.
+    │   └── react-ui - Creates a React UI to give a Lightning Component a React.js web UI
+    ├── install - Installs a Lightning App and/or Component.
+    │   ├── app
+    │   └── component
+    ├── list - Lists Lightning AI self-managed resources (clusters, etc…)
+    │   ├── apps - Lists your Lightning AI Apps.
+    │   └── clusters - Lists your Lightning AI BYOC compute clusters.
+    ├── login - Logs in to your lightning.ai account.
+    ├── logout - Logs out of your lightning.ai account.
+    ├── run - Runs a Lightning App locally or on the cloud.
+    │   └── app - Runs an App from a file.
+    ├── show - Shows given resource.
+    │   ├── cluster - Groups cluster commands inside show.
+    │   │   └── logs - Shows cluster logs.
+    │   └── logs - Shows cloud application logs. By default prints logs for all currently available Components.
+    ├── stop - Stops your App.
+    └── tree - Shows the command tree of your CLI.
+
+Learn more about `Command-line interfaces here <https://en.wikipedia.org/wiki/Command-line_interface>`_.
+
+----
+
+**********
+Learn more
+**********
+
+.. raw:: html
+
+    <div class="display-card-container">
+        <div class="row">
+
+.. displayitem::
+   :header: Develop a Command Line Interface
+   :description: Learn how to develop a CLI for your App.
+   :col_css: col-md-6
+   :button_link: ../../workflows/build_command_line_interface/index_content.html
+   :height: 150
+
+.. raw:: html
+
+        </div>
+    </div>

docs/source-app/glossary/restful_api/restful_api.rst

@@ -0,0 +1,53 @@
+:orphan:
+
+###########
+RESTful API
+###########
+
+**Audience:** Users looking to create an API in their App to allow users to activate functionalities from external sources.
+
+----
+
+**********************
+What is a RESTful API?
+**********************
+
+A RESTful API is a set of external URL routes exposed by a server that enables clients to trigger some functionalities, such as getting or putting some data, uploading files, etc..
+
+This provides great flexibility for users as they can easily discover functionalities made available by the App Builders.
+
+The Lightning App framework supports the four primary HTTP methods: `GET`, `POST`, `PUT`, `DELETE`.
+
+These methods are guidelines to organize your RESTful Services and help users understand your functionalities.
+
+* **`GET`:** Reads data from the server.
+* **`POST`:** Creates new resources.
+* **`PUT`:** Updates/replaces existing resources.
+* **`DELETE`:** Deletes resources.
+
+Learn more about `HTTP Methods for RESTful Services here <https://www.restapitutorial.com/lessons/httpmethods.html#:~:text=The%20primary%20or%20most%2Dcommonly,but%20are%20utilized%20less%20frequently.>`_.
+
+The Lightning App framework uses the popular `FastAPI <https://fastapi.tiangolo.com/>`_ and `Pydantic <https://pydantic-docs.helpmanual.io/>`_ frameworks under the hood. This means you can use all their features while building your App.
+
+----
+
+**********
+Learn more
+**********
+
+.. raw:: html
+
+    <div class="display-card-container">
+        <div class="row">
+
+.. displayitem::
+   :header: Develop a RESTful API
+   :description: Learn how to develop an API for your App.
+   :col_css: col-md-6
+   :button_link: ../../workflows/build_rest_api/index_content.html
+   :height: 150
+
+.. raw:: html
+
+        </div>
+    </div>

docs/source-app/index.rst

@@ -220,8 +220,10 @@ Keep Learning
    Add a web user interface (UI) <workflows/add_web_ui/index>
    Add a web link  <workflows/add_web_link>
    Arrange app tabs <workflows/arrange_tabs/index>
+   Develop a Command Line Interface (CLI) <workflows/build_command_line_interface/index>
    Develop a Lightning App <workflows/build_lightning_app/index>
    Develop a Lightning Component <workflows/build_lightning_component/index>
+   Develop a REST API <workflows/build_rest_api/index>
    Cache Work run calls  <workflows/run_work_once>
    Customize your cloud compute <core_api/lightning_work/compute>
    Extend an existing app <workflows/extend_app>
@@ -264,10 +266,12 @@ Keep Learning
 
    App Components Tree <glossary/app_tree>
    Build Configuration <glossary/build_config/build_config>
+   Command Line Interface (CLI) <glossary/command_lines/command_lines>
    DAG <glossary/dag>
    Event Loop <glossary/event_loop>
    Environment Variables <glossary/environment_variables>
    Frontend <workflows/add_web_ui/glossary_front_end.rst>
+   REST API <glossary/restful_api/restful_api>
    Sharing Components <glossary/sharing_components>
    Scheduling <glossary/scheduling.rst>
    Storage <glossary/storage/storage.rst>

docs/source-app/workflows/build_command_line_interface/app.py

@@ -0,0 +1,36 @@
+from commands.notebook.run import RunNotebook, RunNotebookConfig
+from lit_jupyter import JupyterLab
+
+import lightning as L
+from lightning.app.structures import Dict
+
+
+class Flow(L.LightningFlow):
+
+    def __init__(self):
+        super().__init__()
+        self.notebooks = Dict()
+
+    # 1. Annotates the handler input with the Notebook config.
+    def run_notebook(self, config: RunNotebookConfig):
+        if config.name in self.notebooks:
+            return f"The Notebook {config.name} already exists."
+        else:
+            # 2. Dynamically creates the Notebook if it doesn't exist and runs it.
+            self.notebooks[config.name] = JupyterLab(
+                cloud_compute=L.CloudCompute(config.cloud_compute)
+            )
+            self.notebooks[config.name].run()
+            return f"The Notebook {config.name} was created."
+
+    def configure_commands(self):
+        # 3. Returns a list of dictionaries with the format:
+        # {"command_name": CustomClientCommand(method=self.custom_server_handler)}
+        return [{"run notebook": RunNotebook(method=self.run_notebook)}]
+
+    def configure_layout(self):
+        # 4. Dynamically displays the Notebooks in the Lightning App View.
+        return [{"name": n, "content": w} for n, w in self.notebooks.items()]
+
+
+app = L.LightningApp(Flow())

docs/source-app/workflows/build_command_line_interface/cli.rst

@@ -0,0 +1,144 @@
+:orphan:
+
+###########################################
+1. Develop a CLI with server side code only
+###########################################
+
+We are going to learn how to create a simple command-line interface.
+
+Lightning provides a flexible way to create complex CLI without much effort.
+
+----
+
+*************************
+1. Implement a simple CLI
+*************************
+
+To create your first CLI, you need to override the :class:`~lightning_app.core.flow.LightningFlow.configure_commands` hook and return a list of dictionaries where the keys are the commands and the values are the server side handlers.
+
+First, create a file ``app.py`` and copy-paste the following code in to the file:
+
+.. literalinclude:: example_command.py
+
+----
+
+**************
+2. Run the App
+**************
+
+Execute the following command in a terminal:
+
+.. code-block::
+
+    lightning run app app.py
+
+The following appears the terminal:
+
+.. code-block::
+
+    Your Lightning App is starting. This won't take long.
+    INFO: Your app has started. View it in your browser: http://127.0.0.1:7501/view
+    []
+
+----
+
+***************************
+3. Connect to a running App
+***************************
+
+In another terminal, connect to the running App.
+When you connect to an App, the Lightning CLI is replaced by the App CLI. To exit the App CLI, you need to run ``lightning disconnect``.
+
+.. code-block::
+
+    lightning connect localhost
+
+To see a list of available commands:
+
+.. code-block::
+
+    lightning --help
+    You are connected to the cloud Lightning App: localhost.
+    Usage: lightning [OPTIONS] COMMAND [ARGS]...
+
+    --help     Show this message and exit.
+
+    Lightning App Commands
+        add Description
+
+To find the arguments of the commands:
+
+.. code-block::
+
+    lightning add --help
+    You are connected to the cloud Lightning App: localhost.
+    Usage: lightning add [ARGS]...
+
+    Options
+        name: Add description
+
+----
+
+********************
+4. Execute a command
+********************
+
+Trigger the command line exposed by your App:
+
+.. code-block::
+
+    lightning add --name=my_name
+    WARNING: Lightning Command Line Interface is an experimental feature and unannounced changes are likely.
+
+In your first terminal, **Received name: my_name** and **["my_name"]** are printed.
+
+.. code-block::
+
+    Your Lightning App is starting. This won't take long.
+    INFO: Your app has started. View it in your browser: http://127.0.0.1:7501/view
+    []
+    Received name: my_name
+    ["my_name]
+
+----
+
+**************************
+5. Disconnect from the App
+**************************
+
+To exit the App CLI, you need to run ``lightning disconnect``.
+
+.. code-block::
+
+    lightning disconnect
+    You are disconnected from the local Lightning App.
+
+----
+
+**********
+Learn more
+**********
+
+.. raw:: html
+
+    <div class="display-card-container">
+        <div class="row">
+
+.. displayitem::
+   :header: 2. Implement a CLI with client side code execution
+   :description: Learn how to develop a complex API for your application
+   :col_css: col-md-6
+   :button_link: cli_client.html
+   :height: 150
+
+.. displayitem::
+   :header: Develop a RESTful API
+   :description: Learn how to develop an API for your application.
+   :col_css: col-md-6
+   :button_link: ../build_rest_api/index.html
+   :height: 150
+
+.. raw:: html
+
+        </div>
+    </div>