Refine README.Rmd

Author: coatless

DESCRIPTION

@@ -15,6 +15,7 @@ URL: https://r-pkg.thecoatlessprofessor.com/shinydocker/, https://github.com/coa
 BugReports: https://github.com/coatless-rpkg/shinydocker/issues
 License: AGPL (>= 3)
 SystemRequirements: Docker (>= 28.0.0)
+Depends: R (>= 4.4)
 Imports: 
     yaml,
     processx,

README.Rmd

@@ -3,7 +3,6 @@ output: github_document
 ---
 
 <!-- README.md is generated from README.Rmd. Please edit that file -->
-
 ```{r, include = FALSE}
 knitr::opts_chunk$set(
   collapse = TRUE,
@@ -13,21 +12,20 @@ knitr::opts_chunk$set(
 )
 ```
 
-
-> [!IMPORTANT]
->
-> This package is currently in the prototype/experimental stage. It is not yet
-> available on CRAN and may have bugs or limitations. 
-
-# shinydocker <img src="man/figures/shinydocker-animated-logo.svg" align="right" height="139" />
+# shinydocker <a href="https://r-pkgs.thecoatlessprofessor.com/shinydocker/"><img src="man/figures/shinydocker-animated-logo.svg" align="right" height="138" alt="hex logo for shinydocker" /></a>
 
 <!-- badges: start -->
 [![R-CMD-check](https://github.com/coatless-rpkg/shinydocker/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/coatless-rpkg/shinydocker/actions/workflows/R-CMD-check.yaml)
 ![Prototype](https://img.shields.io/badge/Status-Prototype-orange)
 ![Experimental](https://img.shields.io/badge/Status-Experimental-blue)
 <!-- badges: end -->
 
-`shinydocker` is an R package that streamlines the process of containerizing Shiny applications, supporting both R and Python Shiny apps. 
+`shinydocker` simplifies containerizing Shiny applications by automatically generating Docker configurations, building images, and managing containers. It supports both R and Python Shiny apps with intelligent detection of app type and dependencies.
+
+> [!IMPORTANT]
+>
+> This package is currently in the prototype/experimental stage. It is not yet
+> available on CRAN and may have bugs or limitations.
 
 ## Installation
 
@@ -40,105 +38,225 @@ You can install the development version of `shinydocker` from GitHub with:
 remotes::install_github("coatless-rpkg/shinydocker")
 ```
 
-You will also need to have Docker installed on your system. You can download Docker from the [official website](https://www.docker.com/products/docker-desktop). You do not need to
-log in to Docker to use `shinydocker`.
+### Prerequisites
+
+- R (>= 4.4.0)
+- [Docker](https://www.docker.com/products/docker-desktop) installed and running (no login required)
+  - Optionally, [Docker Compose](https://docs.docker.com/compose/install/) for more advanced container management
 
-## Using shinydocker
+## Quick Start
 
-The package provides a set of functions to automate the process, as well as options for advanced configuration.
+With `shinydocker`, you can containerize your Shiny app in just a few lines of code.
+Here's two ways to get started with the package!
 
-### Exporting a Shiny App to Docker
+### One-Command Export
 
-The `export()` function allows you to convert a Shiny application into a docker 
-containerized application.
+The simplest way to containerize a Shiny app is to use the `shinydocker::export()` function:
 
 ```{r}
-#| label: export-shiny-app-to-docker-generic
+#| label: quick-export
 #| eval: false
-# Automated export: configures, builds, and optionally runs the container
-export("path/to/your/shinyapp", run = TRUE)
+library(shinydocker)
+
+# Export app to Docker with a single command (detects app type automatically)
+shinydocker::export("path/to/your/shinyapp", run = TRUE)
 ```
 
-For example, to convert the "Hello World" Shiny app from the `{shiny}` package
-into a standalone Electron app:
+### Example: Converting the "Hello World" Shiny App
+
+To get started, let's convert the classic "Hello World" Shiny app to a Docker container:
 
 ```{r}
-#| label: export-shiny-app-to-docker-hello-world
+#| label: export-hello-world
 #| eval: false
-# Copy "Hello World" from `{shiny}`
-system.file("examples", "01_hello", package="shiny") |>
-    fs::dir_copy("myapp", overwrite = TRUE)
+# Copy the Hello World example from the shiny package
+app_dir <- "hello_world_app"
+system.file("examples", "01_hello", package = "shiny") |>
+  fs::dir_copy(app_dir, overwrite = TRUE)
 
-shinydocker::export("myapp", run = TRUE)
+# Export to Docker and run
+shinydocker::export(app_dir, run = TRUE, detach = TRUE)
+
+# The console will show a URL where you can access your containerized app
+
+# Stop the container when done
+shinydocker::stop_container()
 ```
 
+### Step-by-Step Workflow
 
-### Manually Dockerizing a Shiny App
+For more control over the containerization process:
 
 ```{r}
-#| label: dockerize-a-shiny-app
+#| label: step-by-step
 #| eval: false
 library(shinydocker)
 
-# Path to your Shiny app
-shiny_app_path <- "path/to/your/shinyapp"
+# 1. Create Docker configuration
+shinydocker::dockerize("path/to/your/shinyapp")
 
-# Create Docker configuration for a Shiny app
-dockerize(shiny_app_path)
+# 2. Build Docker image 
+shinydocker::build_image("path/to/your/shinyapp")
 
-# Build a Docker image
-build_image(shiny_app_path)
+# 3. Run the container on port 8080
+shinydocker::run_container("path/to/your/shinyapp", port = 8080, detach = TRUE)
 
-# Run the container
-run_container(shiny_app_path)
+# 4. When done, stop the container
+shinydocker::stop_container("path/to/your/shinyapp")
 ```
 
-### Diagnostic Tools
+
+### R or Python Shiny Apps
+
+`shinydocker` automatically detects and containerizes either R or Python Shiny apps
+by detecting the app type and dependencies in the app directory. The app type
+is determined by the presence of either a `app.R`/`server.R`/`ui.R` file for R Shiny apps
+or a `app.py`/`server.py`/`ui.py` file for Python Shiny apps. Dependencies are detected
+automatically from the app source for R Shiny apps and a `requirements.txt` file for Python Shiny apps.
+
+Therefore, you can use the same `export()` function for both R and Python Shiny apps:
 
 ```{r}
-#| label: diagnostic-tools
+#| label: python-shiny
 #| eval: false
-# Check Docker environment
-sitrep_docker()
-
-# Analyze app containerization readiness
-sitrep_app_conversion("path/to/your/shinyapp")
+shinydocker::export("path/to/your/python_shinyapp", run = TRUE)
 ```
 
 
+### Examples
+
+More examples are available in the package's [`inst/examples/shiny`](inst/examples/shiny) directory.
 
 ## Advanced Configuration
 
-### Custom Dockerfile
+For more advanced use cases, you can customize the containerization process with additional options.
+You can pass these options to the `dockerize()` function.
+
+### Environment Variables
+
+Pass sensitive information or configuration to your Shiny app:
+
+```{r}
+#| label: env-vars
+#| eval: false
+# Add environment variables to the container
+shinydocker::dockerize("path/to/your/shinyapp", 
+          env_vars = c(
+            API_KEY = "your-secret-key",
+            DB_HOST = "database.example.com",
+            LOG_LEVEL = "INFO"
+          ))
+```
+
+### Custom Port Mapping
+
+```{r}
+#| label: custom-port
+#| eval: false
+# Run the container on a specific port
+shinydocker::run_container("path/to/your/shinyapp", port = 3000)
+```
+
+### Custom Dockerfile Template
+
+For advanced customization, you can provide your own Dockerfile template:
 
 ```{r}
 #| label: custom-dockerfile
 #| eval: false
 # Use a custom Dockerfile template
-dockerize("path/to/your/shinyapp", 
+shinydocker::dockerize("path/to/your/shinyapp", 
           custom_dockerfile = "path/to/custom/Dockerfile")
 ```
 
-### Environment Variables
+## Diagnostic Tools
+
+`shinydocker` provides two situation report (sitrep) functions that offer
+diagnostic information about your Docker environment and app containerization readiness.
+
+### Check Docker Environment
+
+
+```{r}
+#| label: check-docker
+#| eval: false
+# Check if Docker is correctly set up
+shinydocker::sitrep_docker()
+```
+
+### Analyze App Containerization Readiness
 
 ```{r}
-#| label: dockerize
+#| label: check-app
 #| eval: false
-# Set environment variables during containerization
-dockerize("path/to/your/shinyapp", 
-          env_vars = c(API_KEY = "your-secret-key"))
+# Check if your app is ready for containerization
+shinydocker::sitrep_app_conversion("path/to/your/shinyapp")
 ```
 
-## Cleanup and Management
+## Container Management
+
+`shinydocker` provides functions to manage your Shiny app containers so that
+you can start, stop, and clean up containers with ease without needing to remember
+Docker commands or jump into terminal.
+
+### Running Containers
 
 ```{r}
-#| label: cleanup-and-management
+#| label: run-containers
 #| eval: false
-# Stop a specific container
-stop_containers("path/to/your/shinyapp")
+# Run with docker-compose (if available)
+shinydocker::run_container("path/to/your/shinyapp", docker_compose = TRUE)
+
+# Run with plain docker
+shinydocker::run_container("path/to/your/shinyapp", docker_compose = FALSE)
+```
+
+### Stopping Containers
 
-# Clean up Docker containers and images
-cleanup_containers(remove_images = TRUE)
+```{r}
+#| label: stop-containers
+#| eval: false
+# Stop container for a specific app
+shinydocker::stop_container("path/to/your/shinyapp")
+
+# Stop all running containers
+shinydocker::stop_container()
+```
+
+### Cleanup
+
+```{r}
+#| label: cleanup
+#| eval: false
+# Remove containers for a specific app
+shinydocker::cleanup_containers("path/to/your/shinyapp")
+
+# Remove all shinydocker containers and images
+shinydocker::cleanup_containers(remove_images = TRUE, force = TRUE)
+
+# Clean up and run docker system prune
+shinydocker::cleanup_containers(prune = TRUE)
+```
+
+
+## Troubleshooting
+
+If you encounter issues:
+
+1. Run `shinydocker::sitrep_docker()` to check Docker installation
+2. Run `shinydocker::sitrep_app_conversion("path/to/your/shinyapp")` to analyze app issues
+3. Check for port conflicts with `shinydocker::is_port_available(3838)`
+
+Need more help? Consider opening an [issue](https://github.com/coatless-rpkg/shinydocker/issues/new) on the repository.
+
+## Citation
+
+If you use `shinydocker` in your research or project, please consider citing it:
+
+```{r}
+#| label: citation
+#| eval: false
+citation("shinydocker")
 ```
 
 ## License