Generate Project

A Python project folder generator with support for UV and Poetry package managers. The generated folder provides everything you need to get started with a well-structured Python project, including development tasks for formatting, linting, documentation, testing, and CI/CD.

Features

📦 UV or Poetry for dependency management and packaging
🧹 Code quality tools including black, isort, flake8, mypy and pylint
📚 Sphinx based documentation with auto-generated API docs and live preview
✅ Testing framework with pytest and test coverage reports
🔄 GitHub actions with CI/CD workflows for tests, documentation and release management
🐍 PyPl package publishing automation with version control
📝 ReadTheDocs integration for hosting documentation
🚀 Automated release process for versioning and publishing
📋 Project structure following best practices

Requirements

Python 3.10+
Cookiecutter 2.6.0+
PyYAML 6.0.0+
python-dotenv 1.1.0+

Installation

pip install generate-project

Or, if you use Poetry:

poetry add generate-project

Or, if you use UV:

uv add generate-project

Quick Start

Basic Usage

You can provide the project configuration values in the terminal command line:

generate-project generate "project-name" \
--author_name="Your Name" \
--email="your.email@example.com" \
--github_username="yourusername" \
--python_min_version="3.11"
...

Project Configuration Options

These are the most important project configuration options:

Advanced Usage

You can also save your own configuration values to be used as default values:

generate-project config \
--author_name="Your Name" \
--email="your.email@example.com" \
--github_username="yourusername" \
--python_min_version="3.11"

You can also set the default package manager:

generate-project config --manager uv

and then you can omit the saved configuration options:

generate-project generate "project-name"
...

Package Manager

By default, generate-project creates projects using UV. Use the --manager flag to select Poetry instead:

# UV project (default)
generate-project generate my-project

# Poetry project
generate-project generate my-project --manager poetry

Project Structure

The generated project will have the following structure:

project-name/
├── .github/workflows/         # GitHub actions for CI/CD
│   ├── docs.yml               # Documentation building and testing
│   ├── tests.yml              # Code quality and testing
│   ├── release.yml            # Automated releases and publishing
│   └── update_rtd.yml         # Manual ReadTheDocs updates
├── .vscode/                   # VS Code configuration
│   ├── settings.json          # Editor settings, linting, formatting
│   ├── launch.json            # Debug configurations
│   └── tasks.json             # Task definitions
├── docs/                      # Sphinx documentation
│   ├── api/                   # Auto-generated API docs
│   ├── guides/                # User guides
│   ├── conf.py                # Sphinx configuration
│   └── index.md               # Documentation home
├── src/package_name/          # Source code
│   └── __init__.py            # Package initialization
├── tests/                     # Test directory
├── examples/                  # Example usage (libraries only; removed for applications)
├── scripts/                   # Release management scripts
├── .env                       # Environment variables (if --local-env used)
├── .gitignore                 # Git ignore rules
├── .readthedocs.yaml          # ReadTheDocs configuration
├── CLAUDE.md                  # Claude Code integration guide
├── CredentialManagement.md    # Token management documentation
├── LICENSE                    # MIT License
├── Makefile                   # Development commands
├── pyproject.toml             # Project configuration
├── run.sh                     # Development task runner
└── README.md                  # Project documentation

Project Types

By default, generate-project creates an application project with a CLI entry point. Use the --library flag to create a library project instead:

# Create an application (default)
generate-project generate my-app

# Create a library
generate-project generate my-lib --library

Supacode Integration

Use the --supacode flag to generate a supacode.json that wires Supacode's worktree lifecycle hooks (setup/archive/delete) to three new run.sh commands, also exposed as Makefile targets:

generate-project generate my-project --supacode

Each phase also calls an optional scripts/worktree-<phase>.sh per-repo hook if present.

GitHub Repository Setup

The following options are available to setup a github repository for the project:

The following repository secrets can be automatically setup:

TEST_PYPI_TOKEN
PYPI_TOKEN
RTD_TOKEN

The tokens must be available in a .env file located in the directory where generate-project is executed or in any parent directory up the folder hierarchy. If no .env file is found, the application falls back to reading the tokens from environment variables.

Development Workflow

The generated project includes a Makefile with common development tasks:

# Environment Setup
make venv                 # Create and activate a local virtual environment
make install              # Install core dependencies
make install-dev          # Install all development dependencies

# Code quality
make format               # Run code formatters
make lint                 # Run linters
make check                # Run format + lint + tests on all files
make pre-commit           # Run format and lint only on changed files, then tests

# Testing
make test                 # Run tests
make test-cov             # Run tests with coverage
make coverage             # Generate coverage report

# Documentation
make docs-api             # Generate API documentation
make docs                 # Build documentation
make docs-live            # Start live preview server

# Run
make run                  # Run the application, or an example of the library

# Worktree lifecycle (Supacode, requires --supacode)
make worktree-setup       # Prepare a freshly created worktree
make worktree-archive     # Tear down a worktree before archiving
make worktree-delete      # Guardrail + teardown before deleting

# Release tasks will bump the version, create a new release and publish it
make release-major        # Create major release
make release-minor        # Create minor release
make release-micro        # Create micro (patch) release
make release-rc           # Create release candidate
make release-beta         # Create beta pre-release
make release-alpha        # Create alpha pre-release

Each release task bumps the version, updates CHANGELOG.md, writes and commits a RELEASE_NOTES.md (used as the GitHub Release body), then creates the release commit and tag. By default the commit message, tag message, changelog entry and release notes are generated for you (and opened in your editor for review). To prepare them ahead of time, drop drafts in a .tmp_release_docs/ folder — commit.txt, tag.txt, changelog.md, release_notes.md — and any draft present is used instead of the generated text. (The older --changes flag is deprecated in favor of these drafts.)

A companion release-docs Claude Code skill (with a /release-docs command) can draft those files for you from the diff since the last release tag. It is bundled with generate-project alongside two more slash commands — /update-dev-env (sync a generated repo's dev-environment files with a released template, preserving customizations) and /migrate-poetry-to-uv (migrate a Poetry-based generated repo to UV). Install them globally with generate-project install-skills (into ~/.claude), into a new project with generate ... --install-skills, or, in an already-generated project, with python scripts/install_claude_skills.py. See the command reference for details.

Codex users can install the bundled generate-codex-assets bootstrap skill, then ask Codex to generate Codex skills from the same manifest-listed source files. From this repository, copy src/generate_project/claude_assets/skills/generate-codex-assets/ into .agents/skills/ or ~/.agents/skills/. From a generated repository, first run python scripts/install_claude_skills.py to fetch the bundled assets, then copy .claude/skills/generate-codex-assets/ into Codex's skills folder. The bootstrap helper reads asset_manifest.txt locally or from GitHub, so new skills and commands do not need a second hardcoded file list.

Run make help for a complete list of the development tasks available.

Acknowledgments

This project was inspired by the GitHub workflows and automation ideas from phitoduck/python-course-cookiecutter-v2.

While this project is an independent implementation and a full Python application, the original repository provided valuable inspiration for the CI/CD and automation approach.

We thank the original authors for their contributions and ideas.

License

This project is released under the MIT License. See the LICENSE file for details.