From 0c56d031a74920c7b1e730fb49737d56028e419d Mon Sep 17 00:00:00 2001 From: Piotr Pasza Storozenko Date: Mon, 11 Mar 2024 15:20:28 +0000 Subject: [PATCH] docs: polish the readme --- README.md | 76 +++++++++++++++++++++++++++++++++--------------- requirements.txt | 2 ++ 2 files changed, 55 insertions(+), 23 deletions(-) create mode 100644 requirements.txt diff --git a/README.md b/README.md index 6de84ee..8704ad3 100644 --- a/README.md +++ b/README.md @@ -1,35 +1,65 @@ # PyShiny Dashboard Template -## How to run +This template offers a streamlined way to create and deploy Shiny applications using Python. It leverages `poetry` for dependency management and `playwright` for app testing, facilitating both local development and deployment on Posit Connect. -### Devcontainer +## Getting Started -The best way is to use the predefined [devcontainer](https://code.visualstudio.com/docs/devcontainers/containers). -This way just run: +### Using Devcontainer -```sh -poetry shell -shiny run app.py --reload -``` +For a seamless development experience, we recommend using the provided [devcontainer](https://code.visualstudio.com/docs/remote/containers) configuration with Visual Studio Code. This setup encapsulates the development environment, ensuring consistency across machines. -### Poetry +1. **Start the Devcontainer**: Either use [DevPod](https://devpod.sh/) or open the project in VS Code, and when prompted, reopen it in a container. Alternatively, use the Command Palette (`Ctrl+Shift+P`) and select "Remote-Containers: Reopen in Container". Wait for the container to set up. +2. **Activate the virtual environment**: + ```sh + poetry shell + ``` +3. **Run the application**: + ```sh + shiny run app.py --reload + ``` +4. **Execute tests**: + ```sh + poetry run pytest + ``` -This template uses `poetry` for packages management. -The best way to install `poetry` is with `pipx`. +*Note*: The Devcontainer environment may limit the use of `playwright` browser features, such as `codegen`. For these features, consider setting up the project locally. -### Deployment on Posit Connect +### Setting Up Locally with Poetry -First set your `CONNECT_API_KEY` as environmental variable. -Then add your server. -And finally deploy. +For local development without Devcontainer, follow these steps: -```sh -CONNECT_API_KEY="AppsilonAppsilonAppsilonAppsilon" +1. **Install pipx**: [pipx](https://github.com/pypa/pipx) allows you installing CLI apps in isolated environments. This is how we want to install the `poetry`. +1. **Install Poetry** using `pipx`: + ```sh + pipx install poetry + ``` +2. **Clone the repository** and navigate to the project directory. +3. **Install dependencies**: + ```sh + poetry install + playwright install + ``` -rsconnect add \ ---api-key $CONNECT_API_KEY \ ---server \ ---name +*Attention*: The `playwright install` command may prompt additional steps. Follow the instructions provided in the terminal. -rsconnect deploy shiny -t "PyShiny Template" . -``` \ No newline at end of file +### Deployment on Posit Connect + +Deploy your Shiny application to Posit Connect with the following steps: + +1. **Export your Posit Connect API Key**: + ```sh + export CONNECT_API_KEY="your_api_key_here" + ``` +2. **Configure Posit Connect** with your server details: + ```sh + rsconnect add \ + --api-key $CONNECT_API_KEY \ + --server \ + --name + ``` +3. **Deploy the application**: + ```sh + rsconnect deploy shiny -t "PyShiny Template" . + ``` + +Replace placeholders (``, ``, and `your_api_key_here`) with your actual Posit Connect server URL, desired server name, and API key. diff --git a/requirements.txt b/requirements.txt new file mode 100644 index 0000000..3494d50 --- /dev/null +++ b/requirements.txt @@ -0,0 +1,2 @@ +# This is required by Posit Connect to deploy the app +.