examples and documentation

README.md

@@ -1,6 +1,8 @@
 # DEU - Docker Environment Utility
 
 A simple utility to create and manage development containers using Docker Compose.
+It aims to be a sort of envorment manager for docker compose containers so that you can spin
+up local containers quickly in any directory.
 
 ## Overview
 
@@ -13,6 +15,16 @@ chmod +x deu.py
 sudo ln -s $(pwd)/deu.py /usr/local/bin/deu
 ```
 
+## Getting Started
+
+The easiest way to get started is to run:
+
+```bash
+deu examples
+```
+
+This will show you common usage patterns and examples.
+
 ## Usage
 
 ### Initialize a Container
@@ -63,6 +75,12 @@ deu delete my_container
 deu list                 # Shows both local and global containers
 ```
 
+## Getting Help
+
+- Run `deu --help` for general help
+- Run `deu <command> --help` for command-specific help
+- Run `deu examples` for common usage patterns
+
 ## Configuration
 
 `deu` creates two configuration files:

deu.py

@@ -456,18 +456,63 @@ def handle_delete(container_name: Optional[str] = None) -> None:
         sys.exit(1)
 
 
+def handle_examples() -> None:
+    """Show common usage examples."""
+    print(
+        """
+Common DEU Usage Examples:
+
+1. Create a new development container:
+   deu init --image ubuntu:24.04
+   deu init -g --image python:3.11
+   deu init --image node:20 --service my_node_app
+
+2. Work with containers:
+   deu activate              # Start shell in local container
+   deu activate my_container # Start shell in specific container
+   deu background            # Start container in background
+   deu logs                  # View container logs
+
+3. Manage containers:
+   deu stop                  # Stop local container
+   deu rm                    # Remove local container
+   deu delete                # Stop and remove local container
+   deu list                  # Show all available containers
+
+4. Global containers:
+   deu init -g --image ubuntu:24.04  # Create global container
+   deu activate my_global            # Use global container
+   deu delete my_global              # Remove global container
+
+5. Container naming:
+   deu init --image ubuntu:24.04 --service my_dev
+   deu activate my_dev
+   deu delete my_dev
+"""
+    )
+
+
 def main() -> None:
     """Main entry point for the script."""
     parser = argparse.ArgumentParser(
-        description="Development container utility",
+        description="DEU - Docker Environment Utility\n\n"
-        formatter_class=argparse.ArgumentDefaultsHelpFormatter,
+        "A simple utility to create and manage development containers.\n"
+        "Use 'deu examples' to see common usage patterns.",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
     )
     subparsers = parser.add_subparsers(dest="command", help="Command to execute")
 
     # Init command
-    init_parser = subparsers.add_parser("init", help="Initialize a new container")
+    init_parser = subparsers.add_parser(
+        "init",
+        help="Initialize a new development container",
+        description="Create a new development container with the specified image.\n"
+        "Example: deu init --image ubuntu:24.04",
+    )
     init_parser.add_argument("path", nargs="?", help="Path to the .container directory")
-    init_parser.add_argument("--image", required=True, help="Docker image to use")
+    init_parser.add_argument(
+        "--image", required=True, help="Docker image to use (e.g., ubuntu:24.04)"
+    )
     init_parser.add_argument(
         "--service",
         default=generate_service_name(),
@@ -478,50 +523,88 @@ def main() -> None:
         "--global",
         dest="is_global",
         action="store_true",
-        help="Create container in global config",
+        help="Create container in global config (~/.config/deu/)",
     )
 
     # Activate command
-    activate_parser = subparsers.add_parser("activate", help="Activate container shell")
+    activate_parser = subparsers.add_parser(
+        "activate",
+        help="Activate container shell",
+        description="Start an interactive shell in the container.\n"
+        "Example: deu activate my_container",
+    )
     activate_parser.add_argument(
         "container_name", nargs="?", help="Name of the container to activate"
     )
 
     # Background command
     background_parser = subparsers.add_parser(
-        "background", help="Start container in background"
+        "background",
+        help="Start container in background",
+        description="Start the container in detached mode.\n"
+        "Example: deu background my_container",
     )
     background_parser.add_argument(
         "container_name", nargs="?", help="Name of the container to start"
     )
 
     # Logs command
-    logs_parser = subparsers.add_parser("logs", help="Show container logs")
+    logs_parser = subparsers.add_parser(
+        "logs",
+        help="Show container logs",
+        description="View container logs in follow mode.\n"
+        "Example: deu logs my_container",
+    )
     logs_parser.add_argument(
         "container_name", nargs="?", help="Name of the container to show logs for"
     )
 
     # Stop command
-    stop_parser = subparsers.add_parser("stop", help="Stop container")
+    stop_parser = subparsers.add_parser(
+        "stop",
+        help="Stop container",
+        description="Stop a running container.\n" "Example: deu stop my_container",
+    )
     stop_parser.add_argument(
         "container_name", nargs="?", help="Name of the container to stop"
     )
 
     # Remove command
-    rm_parser = subparsers.add_parser("rm", help="Remove container")
+    rm_parser = subparsers.add_parser(
+        "rm",
+        help="Remove container",
+        description="Remove a container and its configuration.\n"
+        "Example: deu rm my_container",
+    )
     rm_parser.add_argument(
         "container_name", nargs="?", help="Name of the container to remove"
     )
 
     # List command
-    subparsers.add_parser("list", help="List all available containers")
+    list_parser = subparsers.add_parser(
+        "list",
+        help="List all available containers",
+        description="Show all containers (local and global).\n" "Example: deu list",
+    )
 
     # Delete command
-    delete_parser = subparsers.add_parser("delete", help="Stop and remove a container")
+    delete_parser = subparsers.add_parser(
+        "delete",
+        help="Stop and remove a container",
+        description="Stop and remove a container in one command.\n"
+        "Example: deu delete my_container",
+    )
     delete_parser.add_argument(
         "container_name", nargs="?", help="Name of the container to delete"
     )
 
+    # Examples command
+    subparsers.add_parser(
+        "examples",
+        help="Show common usage examples",
+        description="Display common usage patterns and examples.",
+    )
+
     args = parser.parse_args()
 
     if args.command == "init":
@@ -542,6 +625,8 @@ def main() -> None:
         handle_list()
     elif args.command == "delete":
         handle_delete(args.container_name)
+    elif args.command == "examples":
+        handle_examples()
     else:
         parser.print_help()
         sys.exit(1)