docs: added better comments and clarity (#49)

Author: Tharun-Techie

Dockerfile

@@ -1,37 +1,36 @@
-# pick the CUDA version your host GPU driver supports
+# GPU-accelerated transcribe-anything Docker image
+# Uses PyTorch CUDA 12.6 runtime for optimal GPU performance
 FROM pytorch/pytorch:2.6.0-cuda12.6-cudnn9-runtime
 
+# Prevent Python from writing bytecode and enable unbuffered output
 ENV PYTHONDONTWRITEBYTECODE=1
 ENV PYTHONUNBUFFERED=1
 
 WORKDIR /app
 
+# Install system dependencies
 RUN apt-get update -y
+RUN apt-get install -y build-essential curl dos2unix
 
-# install any extra system deps
-RUN apt-get install -y build-essential
-RUN apt-get install -y curl dos2unix
-
-
+# Configure NVIDIA Docker runtime for GPU access
 RUN distribution=$(. /etc/os-release;echo  $ID$VERSION_ID)  && \
     curl -s -L https://nvidia.github.io/nvidia-docker/gpgkey | apt-key add -  && \
     curl -s -L https://nvidia.github.io/nvidia-docker/$distribution/nvidia-docker.list | tee /etc/apt/sources.list.d/nvidia-docker.list
 
 RUN apt-get update -y
 RUN apt-get install -y nvidia-container-toolkit
-
 RUN mkdir -p /etc/docker
-
 RUN nvidia-ctk runtime configure --runtime=docker
 
+# Copy source code and prepare entrypoint
 COPY . .
 RUN chmod +x entrypoint.sh && dos2unix entrypoint.sh
+
+# Install transcribe-anything in editable mode
 RUN pip install -e .
 
-# Now install the lengthy list of heavy dependencies so startup is reasonable.
+# Pre-initialize GPU dependencies to reduce startup time
 RUN /bin/bash /app/entrypoint.sh --only-check-shared-libs && transcribe-anything-init-insane
 
 ENTRYPOINT ["/app/entrypoint.sh"]
 CMD ["--help"]
-
-

docker-compose.yml

@@ -1,11 +1,14 @@
 services:
   transcribe:
     build: .
-    # Enable GPU access
+    
+    # Enable GPU access for CUDA acceleration
     deploy:
       resources:
         reservations:
           devices:
             - capabilities: [gpu]
+    
+    # Expose container port 80 on host port 8092
     ports:
       - "8092:80"

entrypoint.sh

@@ -1,6 +1,9 @@
 #!/bin/bash
 
-# Add these libraries.
+# GPU-accelerated transcribe-anything launcher
+# Configures CUDA library paths and validates shared libraries
+
+# Configure CUDA library paths for conda-installed NVIDIA packages
 export LD_LIBRARY_PATH=/opt/conda/lib/python3.11/site-packages/nvidia/cuda_runtime/lib:${LD_LIBRARY_PATH}
 export LD_LIBRARY_PATH=/opt/conda/lib/python3.11/site-packages/nvidia/cuda_runtime/lib64:${LD_LIBRARY_PATH}
 export LD_LIBRARY_PATH=/opt/conda/lib/python3.11/site-packages/nvidia/cudnn/lib:${LD_LIBRARY_PATH}
@@ -12,8 +15,7 @@ export LD_LIBRARY_PATH=/opt/conda/lib/python3.11/site-packages/nvidia/curand/lib
 export LD_LIBRARY_PATH=/opt/conda/lib/python3.11/site-packages/nvidia/cublas/lib/:${LD_LIBRARY_PATH}
 export LD_LIBRARY_PATH=/opt/conda/lib/python3.11/site-packages/nvidia/nccl/lib/:${LD_LIBRARY_PATH}
 
-
-# Check
+# Validate CUDA shared libraries
 if python3 check_linux_shared_libraries.py
 then
     echo "✓ check_linux_shared_libraries.py"
@@ -22,10 +24,11 @@ else
     exit 1
 fi
 
-# if --only-check
+# Exit early if only checking libraries
 if [[ "$1" == "--only-check-shared-libs" ]]; then
     echo "✓ --only-check-shared-libs"
     exit 0
 fi
 
-transcribe-anything "$@"
+# Launch transcribe-anything with GPU acceleration
+transcribe-anything "$@"

install

@@ -1,25 +1,36 @@
 #!/bin/bash
+
+#==============================================================================
+# UV Environment Setup for transcribe-anything
+# Creates Python 3.11 venv, installs dependencies, creates activation symlinks
+#==============================================================================
+
+# Enable error handling and command tracing
 set -e
 set -x
+
+# Create virtual environment and install dependencies
 uv venv --python 3.11
 uv pip install -r requirements.testing.txt
 uv pip install -e . --refresh-package uv-iso-env
-# This is needed to force the installation to finalize.
+
+# Finalize installation
 uv run python -c "import os; _ = os.getcwd()"
 set +e
 
-# if ./activate exists, remove it
+# Remove existing activation symlink
 if [ -f activate ]; then
     rm activate
 fi
-# symlink activate to .venv/bin/activate on linux/mac and .venv/Scripts/activate on windows
+
+# Create platform-specific activation symlink
 if [[ "$OSTYPE" == "linux-gnu"* || "$OSTYPE" == "darwin"* ]]; then
     ln -s .venv/bin/activate activate
 else
     ln -s .venv/Scripts/activate activate
 fi
 
-# if on windows symlink .venv/bin -> .venv/Scripts
+# Windows compatibility: link bin -> Scripts
 if [[ "$OSTYPE" == "msys" ]]; then
     if [ -d .venv/bin ]; then
         rm -rf .venv/Scripts

lint

@@ -1,31 +1,36 @@
-#! /bin/bash
+#!/bin/bash
 
+# Python code quality and formatting automation script
+# Runs black, isort, ruff, and mypy on src and tests directories
 
 echo activating venv...
 . ./activate
 
+# Exit on any command failure
 set -e
 
 echo installing pip dependencies
 
-
+# Format code with black (first pass)
 echo running black...
 uv run black src tests --exclude 'src/transcribe_anything/venv'
 
+# Sort imports with isort
 echo running isort...
 uv run isort src tests
 
+# Format code with black again (ensures consistency after import sorting)
 echo re-running black now
-uv run black src tests  --exclude 'src/transcribe_anything/venv'
+uv run black src tests --exclude 'src/transcribe_anything/venv'
 
-# does --clean exist
+# Run ruff linter with auto-fix (unless --no-ruff flag is passed)
 if [[ $* == *--no-ruff* ]]; then
     echo skipping ruff...
 else
     echo running ruff...
     uv run ruff check --fix src tests
 fi
 
-
+# Run mypy for static type checking
 echo running mypy...
-uv run mypy src tests --exclude 'src/transcribe_anything/venv'
+uv run mypy src tests --exclude 'src/transcribe_anything/venv'

tox.ini

@@ -1,19 +1,23 @@
-# content of: tox.ini , put in same dir as setup.py
+# Tox configuration for automated testing and code quality checks
+# Place in same directory as setup.py
 [tox]
 envlist = py310
 
+# Flake8 linter configuration
 [flake8]
-per-file-ignores = __init__.py:F401
-ignore = E501, E203, W503, E731
+per-file-ignores = __init__.py:F401  # Allow unused imports in __init__.py files
+ignore = E501, E203, W503, E731      # Ignore line length, whitespace, and lambda warnings
 
+# Test environment configuration
 [testenv]
-# install pytest in the virtualenv where commands will be executed
+# Install project and testing dependencies
 deps =
-    -e {toxinidir}/.
+    -e {toxinidir}/.                    # Install project in editable mode
     -r{toxinidir}/requirements.testing.txt
+
+# Run code quality checks and tests
 commands =
-    flake8 transcribe_anything tests install_cuda.py
-    pylint transcribe_anything tests install_cuda.py
-    mypy transcribe_anything tests install_cuda.py
-    # NOTE: you can run any command line tool here - not just tests
-    python -m unittest discover tests
+    flake8 transcribe_anything tests install_cuda.py    # Lint code style
+    pylint transcribe_anything tests install_cuda.py    # Static code analysis
+    mypy transcribe_anything tests install_cuda.py      # Type checking
+    python -m unittest discover tests                   # Run unit tests