diff --git a/README.md b/README.md index 42f4cc9..15df31b 100644 --- a/README.md +++ b/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 --help` for command-specific help +- Run `deu examples` for common usage patterns + ## Configuration `deu` creates two configuration files: diff --git a/deu.py b/deu.py index 397b420..a03428e 100755 --- a/deu.py +++ b/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", - formatter_class=argparse.ArgumentDefaultsHelpFormatter, + description="DEU - Docker Environment Utility\n\n" + "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)