words

README.md

@@ -1,2 +1,79 @@
 # textual-serve
-Serve Textual apps locally
+
+Textual serve turns your [Textual](https://github.com/textualize/textual) app in to a web application.
+
+
+## Getting Started
+
+First, [install (or upgrade) Textual](https://textual.textualize.io/getting_started/#installation).
+
+Then install `textual-serve` from Pypi:
+
+
+```
+pip install textual-serve
+```
+
+## Creating a server
+
+The API is super simple. First import the Server class:
+
+```python
+from textual_serve.server import Server
+```
+
+Then create a server instance and pass the command that launches your Textual app:
+
+```python
+server = Server("python -m textual")
+```
+
+The command can be anything you would enter in the shell, as long as it results in a Textual app running.
+
+Finally, call the `serve` command:
+
+```python
+server.server()
+```
+
+You will now be able to click on the link in the terminal to run your app in a browser.
+
+### Summary
+
+Run this code, visit http://localhost:8000
+
+```python
+from textual_serve.server import Server
+
+server = Server("python -m textual")
+server.serve()
+```
+
+## Configuration
+
+The `Server` class has the following parameters:
+
+| parameter      | description                                                                        |
+| -------------- | ---------------------------------------------------------------------------------- |
+| command        | A shell command to launch a Textual app                                            |
+| host           | The host of the web application (defaults to "localhost")                          |
+| port           | The port for the web application (defaults to 8000)                                |
+| title          | The title show in the web app on load, leave as `None` to use the command          |
+| public_url     | The public URL, if the server is behind a proxy. `None` for the local URL          |
+| statics_path   | Path to statics folder, relative to server.py. Default uses directory in module.   |
+| templates_path | Path to templates folder, relative to server.py. Default uses directory in module. |
+
+The `Server.serve` method accepts a `debug` parameter.
+When set to `True`, this will enable [textual devtools](https://textual.textualize.io/guide/devtools/).
+
+## How does it work?
+
+When you visit the app URL, the server launches an instance of your app in a subprocess, and communicates with it via a websocket.
+
+This means that you can serve multiple Textual apps across all the CPUs on your system.
+
+!!! note
+
+    Textual-serve uses a custom protocol to communicate with Textual apps.
+    It *does not* simply run a shell in your browser.
+    This means that there is no way for a user of the app to do anything malicious.

src/textual_serve/server.py

@@ -18,7 +18,6 @@ import jinja2
 from importlib.metadata import version
 
 from rich.console import Console
-from rich.panel import Panel
 from rich.logging import RichHandler
 from rich.highlighter import RegexHighlighter
 
@@ -26,8 +25,7 @@ from .app_service import AppService
 
 log = logging.getLogger("textual-serve")
 
-LOGO = r"""[bold magenta]
-___ ____ _  _ ___ _  _ ____ _       ____ ____ ____ _  _ ____ 
+LOGO = r"""[bold magenta]___ ____ _  _ ___ _  _ ____ _       ____ ____ ____ _  _ ____ 
  |  |___  \/   |  |  | |__| |    __ [__  |___ |__/ |  | |___ 
  |  |___ _/\_  |  |__| |  | |___    ___] |___ |  \  \/  |___ [not bold]VVVVV
 """.replace("VVVVV", f"v{version('textual-serve')}")
@@ -162,7 +160,7 @@ class Server:
 
         self.console.print(LOGO, highlight=False)
         self.console.print(f"Serving {self.command!r} on {self.public_url}")
-        self.console.print("\n[yellow]Press Ctrl+C to quit")
+        self.console.print("\n[cyan]Press Ctrl+C to quit")
 
     def serve(self, debug: bool = False) -> None:
         """Serve the Textual application.