sankalp/djinit
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 13 Wiki Activity

docs: improve README with detailed features, structures, commands, and setup instructions

Browse Source
This commit is contained in:
sankalp committed 2025-11-09 15:30:56 +05:45
1 parent 211219247d
commit fc5de30cb7
1 file changed
+323 -66
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+323 -66
View File
@@ -13,16 +13,19 @@
A fast, interactive CLI to bootstrap a modern, production‑ready Django project in minutes — featuring split settings, DRF and JWT integration, OpenAPI docs, CORS, static file handling via WhiteNoise, Postgres‑friendly configuration, CI/CD templates, deployment helpers, and battle‑tested defaults that deliver a polished developer experience out of the box.
- ✨ Split settings: `settings/base.py`, `settings/development.py`, `settings/production.py`
- 🧱 Optional nested apps layout (e.g., `apps/`)
- 🧩 App scaffolding: URLs, serializers, routes
- 🔗 Project URLs wired automatically
- 🧰 Utility files: `.gitignore`, `README.md`, `.env.sample`, `requirements.txt`, `pyproject.toml`
- 🚀 Deploy helpers: `Justfile`, `Procfile`, `runtime.txt`
- 🛠️ CI/CD: GitHub Actions and/or GitLab CI
- 🎨 Polished UX with `rich`
## Features
---
- ✨ **Split settings**: `settings/base.py`, `settings/development.py`, `settings/production.py`
- 🏗️ **Three structure types**: Standard Django layout, Predefined structure, or Unified structure
- 🧱 **Flexible app layout**: Flat or nested apps package (e.g., `apps/`)
- 🧩 **Complete app scaffolding**: URLs, serializers, routes, views, models, admin, tests
- 🔗 **Auto-wired URLs**: Project URLs automatically include your apps
- 🧰 **Essential utility files**: `.gitignore`, `README.md`, `.env.sample`, `requirements.txt`, `pyproject.toml`
- 🚀 **Deployment helpers**: `Justfile`, `Procfile`, `runtime.txt`
- 🛠️ **CI/CD templates**: GitHub Actions and/or GitLab CI workflows
- 🔐 **Secret key generator**: Generate secure Django secret keys
- 🎨 **Polished UX**: Beautiful interactive interface with `rich` library
- 📦 **App management**: Add apps to existing projects with automatic settings configuration
## Installation
@@ -52,9 +55,9 @@ cd djinit
pip install -e .
```
Requirements: Python 3.13+
**Requirements**: Python 3.13+
## Quick start
## Quick Start
Run the interactive setup:
@@ -64,83 +67,337 @@ djinit setup
dj setup
```
Prompts include:
The interactive setup will guide you through:
- Project directory
- Django project name (used by `django-admin startproject`)
- Apps layout (flat vs nested package like `apps/`)
- App names (comma‑separated)
- CI/CD choice (GitHub, GitLab, both, none)
- Database config preference (`DATABASE_URL` vs individual params)
1. **Structure Type Selection**:
- Standard structure (default Django layout)
- Predefined structure (`apps/users`, `apps/core`, `api/` layout)
- Unified structure (`core/`, `apps/core`, `apps/api` layout)
2. **Project Configuration**:
- Project directory (or use current directory with `.`)
- Django project name (used for the config module)
- Apps layout (flat vs nested package like `apps/`)
- App names (comma‑separated)
3. **CI/CD Configuration**:
- GitHub Actions only
- GitLab CI only
- Both (GitHub Actions + GitLab CI)
- None (skip CI/CD)
4. **Database Configuration**:
- Use `DATABASE_URL` (recommended for production)
- Use individual database parameters
## Commands
- `djinit setup` or `dj setup` — Launch the interactive project generator
- `djinit app <names>` or `dj app <names>` — Create one or more Django apps in an existing project
- Examples:
- `djinit app users` or `dj app users`
- `djinit app users,products,orders` or `dj app users,products,orders`
- `djinit app users products orders` or `dj app users products orders`
- `djinit secret [--count N] [--length L]` or `dj secret [--count N] [--length L]` — Print random Django `SECRET_KEY` values
- Example: `djinit secret --count 5 --length 50`
### Setup Command
## What gets generated
Launch the interactive project generator:
- Django project and apps, then structure validation
- Settings package and split settings
- Base/development/production settings
- Utility files
- App files: `urls.py`, `serializers.py`, `routes.py`
- Project `urls.py` (auto‑includes your apps)
- Updated `wsgi.py`, `asgi.py`, `manage.py`
- `Justfile`, `Procfile`, `runtime.txt`
- CI/CD workflows (per your selection)
```bash
djinit setup
# or
dj setup
```
### Output highlights
### App Command
- `config/settings/` → `__init__.py`, `base.py`, `development.py`, `production.py`
- `apps/<app>/` → `urls.py`, `serializers.py`, `routes.py`
- Project root → `.gitignore`, `README.md`, `.env.sample`, `requirements.txt`, `pyproject.toml`, `Justfile`, `Procfile`, `runtime.txt`
- CI/CD → `.github/workflows/` and/or `.gitlab-ci.yml`
Create one or more Django apps in an existing project:
Note: If you choose a nested apps package (e.g., `apps`), imports and `INSTALLED_APPS` entries are configured accordingly.
```bash
djinit app <names>
# or
dj app <names>
```
## Included packages (by default)
**Examples**:
Generated `requirements.txt` includes:
- `djinit app users` or `dj app users`
- `djinit app users,products,orders` or `dj app users,products,orders`
- `djinit app users products orders` or `dj app users products orders`
- Django
- python-dotenv
- django-jazzmin
- djangorestframework
- djangorestframework-simplejwt
- drf-spectacular
- django-cors-headers
- whitenoise
- psycopg2-binary
- gunicorn
- dj-database-url (when you opt into `DATABASE_URL`)
The app command automatically:
These give you a ready‑to‑use stack with DRF, JWT auth, OpenAPI schema generation, CORS, static files in production, and Postgres support.
- Creates the app with all necessary files
- Adds the app to `INSTALLED_APPS` in `settings/base.py`
- Configures URLs if using predefined structure
- Detects and respects your project's structure (nested/flat)
## Environment and database
### Secret Command
- A `.env.sample` is generated to get you started.
- If you opt into `DATABASE_URL`, `production.py` expects an environment variable like:
`postgres://user:password@host:port/database`
Generate secure Django `SECRET_KEY` values:
```bash
djinit secret [--count N] [--length L]
# or
dj secret [--count N] [--length L]
```
**Examples**:
- `djinit secret` - Generate 3 keys with default length (50)
- `djinit secret --count 5 --length 50` - Generate 5 keys of length 50
- `dj secret --count 10 --length 64` - Generate 10 keys of length 64
## Project Structure Types
### Standard Structure
The default Django layout with split settings:
```
project_name/
├── manage.py
├── project_name/
│ ├── __init__.py
│ ├── settings/
│ │ ├── __init__.py
│ │ ├── base.py
│ │ ├── development.py
│ │ └── production.py
│ ├── urls.py
│ ├── wsgi.py
│ └── asgi.py
├── apps/ # Optional nested apps
│ └── <app_name>/
│ ├── urls.py
│ ├── serializers.py
│ ├── routes.py
│ └── ...
└── <app_name>/ # Or flat apps
└── ...
```
### Predefined Structure
A production-ready structure with `apps/` and `api/` packages:
```
project_name/
├── manage.py
├── config/ # Django config module
│ ├── settings/
│ │ ├── base.py
│ │ ├── development.py
│ │ └── production.py
│ └── urls.py
├── apps/
│ ├── users/ # Pre-configured users app
│ │ ├── models/
│ │ ├── serializers/
│ │ ├── views/
│ │ ├── services/
│ │ └── tests/
│ └── core/ # Core utilities
│ ├── exceptions.py
│ ├── utils/
│ ├── mixins/
│ └── middleware/
└── api/
├── urls.py
└── v1/
└── urls.py
```
### Unified Structure
A unified structure with `core/` as the main module:
```
project_name/
├── manage.py
├── core/ # Main Django config
│ ├── settings/
│ │ ├── base.py
│ │ ├── development.py
│ │ └── production.py
│ ├── urls.py
│ ├── wsgi.py
│ └── asgi.py
└── apps/
├── core/ # Core app with models, utils
│ ├── models/
│ └── utils/
└── api/ # API app
└── ...
```
## What Gets Generated
### Core Files
- **Django project structure** with split settings
- **Settings package**: `base.py`, `development.py`, `production.py`
- **Project URLs**: Auto-configured with app includes
- **WSGI/ASGI**: Production-ready application entry points
- **manage.py**: Django management script
### App Files
Each app includes:
- `urls.py` - URL routing
- `serializers.py` - DRF serializers
- `routes.py` - API route definitions
- `views.py` - View classes
- `models.py` - Database models
- `admin.py` - Admin configuration
- `tests.py` - Test structure
- `apps.py` - App configuration
- `migrations/` - Migration directory
### Utility Files
- `.gitignore` - Comprehensive Python/Django gitignore
- `README.md` - Project documentation template
- `.env.sample` - Environment variables template (includes `SECRET_KEY` placeholder, `DATABASE_URL` or individual DB params, email settings)
- `requirements.txt` - All necessary dependencies
- `pyproject.toml` - Modern Python project configuration (includes ruff linting/formatting config)
- `Justfile` - Development commands (migrations, server, etc.) using `uv run`
- `Procfile` - PaaS deployment configuration (Heroku, Railway, Render, etc.) with release task for migrations
- `runtime.txt` - Python version specification
### CI/CD Files
- `.github/workflows/ci.yml` - GitHub Actions workflow (if selected)
- `.gitlab-ci.yml` - GitLab CI configuration (if selected)
## Included Packages
The generated `requirements.txt` includes:
- **Django** - Web framework
- **python-dotenv** - Environment variable management
- **django-jazzmin** - Modern Django admin interface
- **djangorestframework** - REST API framework
- **djangorestframework_simplejwt** - JWT authentication (note: underscore in package name)
- **drf-spectacular** - OpenAPI 3.0 schema generation
- **django-cors-headers** - CORS handling
- **whitenoise** - Static file serving for production
- **psycopg2-binary** - PostgreSQL adapter
- **gunicorn** - Production WSGI server
- **dj-database-url** - Database URL parsing (when using `DATABASE_URL`)
This gives you a complete stack with:
- REST API with DRF
- JWT authentication endpoints: `/token/`, `/token/refresh/`, `/token/blacklist/`
- OpenAPI documentation at `/docs/` and `/schema/` (available in DEBUG mode only)
- CORS support (configured for localhost:3000 in development)
- Production-ready static file handling with WhiteNoise
- PostgreSQL support (SQLite in development by default)
## Environment and Database
### Environment Variables
A `.env.sample` file is generated with:
- `DJANGO_SETTINGS_MODULE` - Settings module path
- `SECRET_KEY` - Placeholder for your secret key (use `djinit secret` to generate)
- `ALLOWED_HOSTS` - Comma-separated list of allowed hosts
- Database configuration (either `DATABASE_URL` or individual `DB_NAME`, `DB_USER`, `DB_PASSWORD`, `DB_HOST`, `DB_PORT`)
- Email settings (SMTP configuration)
### Database Configuration
**Development (Default)**
- Uses SQLite (`db.sqlite3`) for local development
- No database configuration needed
**Production**
**Option 1: DATABASE_URL (Recommended)**
If you opt into `DATABASE_URL`, the production settings use `dj-database-url`:
```
DATABASE_URL=postgres://user:password@host:port/database
```
**Option 2: Individual Parameters**
Traditional Django database configuration with separate environment variables:
- `DB_NAME` - Database name
- `DB_USER` - Database user
- `DB_PASSWORD` - Database password
- `DB_HOST` - Database host
- `DB_PORT` - Database port
## Development Workflow
After setup, use the generated `Justfile` for common tasks (uses `uv` by default):
```bash
just dev # Start development server (uv run python manage.py runserver)
just migrate # Run migrations
just makemigrations # Create migrations
just shell # Django shell
just test # Run tests
just format # Format code with ruff
just lint # Lint code with ruff
just setup # Complete setup (uv sync + migrate + createsuperuser)
just server # Start production server with gunicorn
```
**Note**: The Justfile uses `uv run` for all commands. If you're not using `uv`, you can modify the Justfile or use Django commands directly.
### API Endpoints
The generated project includes:
- **Admin**: `/admin/`
- **JWT Authentication**:
- `/token/` - Obtain access token
- `/token/refresh/` - Refresh access token
- `/token/blacklist/` - Blacklist refresh token
- **API Documentation** (DEBUG mode only):
- `/docs/` - Swagger UI
- `/schema/` - OpenAPI schema
### Settings Configuration
- **Base Settings** (`settings/base.py`):
- DRF configuration with JWT authentication
- CORS settings
- WhiteNoise for static files
- Security headers
- Pagination (20 items per page)
- **Development Settings** (`settings/development.py`):
- SQLite database
- DEBUG = True
- Console email backend
- CORS allows all origins
- Generated secret key (replace in production)
- **Production Settings** (`settings/production.py`):
- PostgreSQL database (via `DATABASE_URL` or individual params)
- DEBUG = False
- Security settings (HTTPS redirect, HSTS, secure cookies)
- SMTP email configuration
- Secret key from environment variable
## Contributing
Contributions are welcome!
Please open an issue for bugs/ideas. PRs with clear descriptions are appreciated.
Contributions are welcome! Please:
1. Open an issue for bugs or feature ideas
2. Fork the repository
3. Create a feature branch
4. Submit a pull request with a clear description
## Acknowledgments
- Django and the Django community
- Jinja2
- rich
- click
- ruff
- Jinja2 - Template engine
- rich - Beautiful terminal output
- click - CLI framework
- ruff - Fast Python linter and formatter
## License