diff --git a/README.md b/README.md index 1a55150..1d57567 100644 --- a/README.md +++ b/README.md @@ -11,7 +11,7 @@ -**djinit** helps you set up a production-ready Django project in minutes. No more copy-pasting settings or manually wiring up apps, just answer a few questions and get a modern Django project with REST API, authentication, documentation, and deployment configs ready to go. +**djinit** helps you set up a production‑ready Django project in minutes. No more copy‑pasting settings or manually wiring up apps—just answer a few questions and get a modern Django project with REST API, authentication, documentation, and deployment configs ready to go. ## Why djinit? @@ -37,63 +37,51 @@ Or with uv: uv tool install djinitx ``` -**Requirements**: Python 3.13+ +**Requirements**: Python 3.13+ ## Getting Started -Just run: - ```bash djinit setup ``` -You can also use the shorter alias: +or the shorter alias: ```bash dj setup ``` -The tool will ask you a few questions: +The wizard will ask you a few questions: -1. **What structure do you want?** - - **Standard**: Classic Django layout with split settings - - **Predefined**: Organized with `apps/` and `api/` folders (great for larger projects) - - **Unified**: Everything under `core/` and `apps/` (clean and minimal) - - **Single Folder**: All apps in one configurable folder (simple and flat) +1. **What structure do you want?** + - **Standard** – Classic Django layout with split settings + - **Predefined** – Organized with `apps/` and `api/` folders (great for larger projects) + - **Unified** – Everything under `core/` and `apps/` (clean and minimal) + - **Single Folder** – All apps in one configurable folder (simple and flat) -2. **Project Setup**: - - Where to create it (use `.` for current directory) - - Project name (or directory name for Single Folder) +2. **Project Setup** – Destination directory (use `.` for current) and project name. -3. **Database Configuration**: - - Use `DATABASE_URL` (cleaner, recommended) - - Or separate DB variables - - Choose between PostgreSQL or MySQL +3. **Database Configuration** – Choose `DATABASE_URL` (recommended) or individual variables; pick PostgreSQL or MySQL. -4. **Django Apps** (Standard Structure only): - - Whether to use an `apps/` folder - - Which apps to create +4. **Django Apps** *(Standard structure only)* – Whether to create an `apps/` folder and which apps to scaffold. -5. **CI/CD Pipeline**: - - GitHub Actions, GitLab CI, both, or skip it +5. **CI/CD Pipeline** – GitHub Actions, GitLab CI, both, or skip it. -That's it! Your project will be ready with everything configured. +That’s it—your project will be ready with everything configured. ## What You Get -Every project includes: - -- **Split settings** for development and production -- **Django REST Framework** with JWT authentication -- **API documentation** (Swagger UI at `/docs/`) -- **CORS** configured for local development -- **WhiteNoise** for serving static files -- **PostgreSQL** support (SQLite for dev) -- **Modern admin** interface (django-jazzmin) -- **Deployment ready** with Procfile and runtime.txt -- **Development tools** (Justfile with common commands) -- **Environment template** (.env.sample) -- **Git ready** (.gitignore included) +- **Split settings** for development and production +- **Django REST Framework** with JWT authentication +- **API documentation** (Swagger UI at `/docs/`) +- **CORS** configured for local development +- **WhiteNoise** for static files +- **PostgreSQL** support (SQLite for dev) +- **Modern admin** interface (`django-jazzmin`) +- **Deployment ready** with `Procfile` and `runtime.txt` +- **Development tools** (`Justfile` with common commands) +- **Environment template** (`.env.sample`) +- **Git ready** (`.gitignore` included) ## Commands @@ -103,13 +91,13 @@ Every project includes: djinit setup ``` -### Add Apps to Existing Project +### Add Apps to an Existing Project ```bash djinit app users products orders ``` -This automatically creates the apps, adds them to `INSTALLED_APPS`, and wires up URLs. +Creates the apps, adds them to `INSTALLED_APPS`, and wires up URLs. ### Generate Secret Keys @@ -117,14 +105,12 @@ This automatically creates the apps, adds them to `INSTALLED_APPS`, and wires up djinit secret ``` -Need more? Use `--count 5` or change length with `--length 64`. +Use `--count 5` to generate five keys or `--length 64` to change the length. ## Project Structures ### Standard Structure -The classic Django layout with split settings: - ``` myproject/ ├── manage.py @@ -138,8 +124,6 @@ myproject/ ### Single Folder Layout -Simple structure with all apps in one folder: - ``` myproject/ ├── manage.py @@ -147,7 +131,7 @@ myproject/ │ ├── settings/ │ ├── urls.py │ ├── models/ # All models here -│ ├── api/ # API views and serializers +│ ├── api/ # API views & serializers │ │ └── your_model_name/ │ │ ├── views.py │ │ ├── serializers.py @@ -157,8 +141,6 @@ myproject/ ### Predefined Structure -Organized for larger projects: - ``` myproject/ ├── manage.py @@ -174,8 +156,6 @@ myproject/ ### Unified Structure -Clean and minimal: - ``` myproject/ ├── manage.py @@ -193,7 +173,7 @@ myproject/ ## Development Workflow -Your project comes with a `Justfile` for common tasks: +Your project ships with a `Justfile` for common tasks: ```bash just dev # Start dev server @@ -205,52 +185,90 @@ just format # Format code just lint # Lint code ``` -Don't have `just` installed? No problem—these are just shortcuts for standard Django commands. +If you don’t have `just` installed, these are just shortcuts for the equivalent Django commands. ## What's Included ### Packages -- Django (web framework) -- Django REST Framework (API) -- djangorestframework-simplejwt (JWT auth) -- drf-spectacular (API docs) -- django-cors-headers (CORS) -- django-jazzmin (modern admin) -- whitenoise (static files) -- psycopg2-binary (PostgreSQL) -- gunicorn (production server) -- python-dotenv (environment variables) +- **Django** – Web framework +- **Django REST Framework** – API toolkit +- **djangorestframework‑simplejwt** – JWT authentication +- **drf‑spectacular** – OpenAPI/Swagger docs +- **django‑cors‑headers** – CORS handling +- **django‑jazzmin** – Modern admin UI +- **whitenoise** – Static file serving +- **psycopg2‑binary** – PostgreSQL driver +- **gunicorn** – Production WSGI server +- **python‑dotenv** – `.env` handling ### API Endpoints -- `/admin/` - Django admin -- `/token/` - Get JWT token -- `/token/refresh/` - Refresh token -- `/docs/` - Swagger UI (dev only) -- `/schema/` - OpenAPI schema (dev only) +| Endpoint | Description | +|-------------------|---------------------------------| +| `/admin/` | Django admin | +| `/token/` | Obtain JWT token | +| `/token/refresh/` | Refresh JWT token | +| `/docs/` | Swagger UI (dev only) | +| `/schema/` | OpenAPI schema (dev only) | -### Settings +### Settings Overview -**Development**: SQLite, debug mode, console emails, permissive CORS -**Production**: PostgreSQL, security hardened, SMTP emails, strict CORS +- **Development** – SQLite, `DEBUG=True`, console email backend, permissive CORS. +- **Production** – PostgreSQL, hardened security settings, SMTP email backend, strict CORS. ## Environment Setup -Copy `.env.sample` to `.env` and fill in your values: +Copy the sample file and fill in your values: ```bash -SECRET_KEY=your-secret-key-here # Use: djinit secret +cp .env.sample .env +``` + +```dotenv +SECRET_KEY=your-secret-key-here # Generate with: djinit secret DATABASE_URL=postgres://user:pass@host:5432/db ALLOWED_HOSTS=yourdomain.com,www.yourdomain.com ``` -For development, SQLite works out of the box—no database setup needed! +SQLite works out of the box for development—no extra DB setup required. + +## Roadmap + +The following items are tracked in **TODO.md** and represent the near‑future direction of djinit. + +### Planned Features +- **Docker Support** – Auto‑generate a `Dockerfile` for containerized deployments. +- **Frontend Integration** – Scaffold React, Vue, or HTMX alongside the Django backend. +- **Celery Integration** – Simplify background task setup with Celery. +- **More Packages** – Add optional integrations for popular Django packages. + +### Enhancements +- **Add more project structure templates** – Expand the set of ready‑made layouts. +- **Add testing framework setup** – Provide pytest and coverage configuration out of the box. +- **Fix bugs** – Ongoing maintenance and bug resolution. + +### Completed +- **Interactive configuration wizard** – Streamlined project creation experience. +- **Improved structure detection** – Smarter detection of existing Django layouts. + +> Contributions that address any of the above items are highly welcome! ## Contributing Found a bug or have an idea? Open an issue or submit a pull request. Contributions are always welcome! +1. Fork the repository. +2. Create a feature branch (`git checkout -b feature/awesome-feature`). +3. Make your changes and ensure tests pass (`just test`). +4. Submit a pull request with a clear description of the change. + +Please follow the existing code style (ruff + black) and include tests for new functionality. + ## License -MIT © Sankalp Tharu +MIT © Sankalp Tharu + +--- + +*© 2024 Sankalp Tharu. All rights reserved.* \ No newline at end of file