Kivy Project Portfolio

You've poured time into learning Kivy, building calculators, to-do apps, and maybe a weather widget or two. But there's a gap between writing code and being a developer: your projects are scattered across folders, lack READMEs, and show no progression. When a recruiter or client opens your GitHub, they see a mess — not the story of your growth. This lesson is the bridge: you'll learn how to assemble a complete Kivy mobile project portfolio that turns your raw code into a compelling, professional narrative. By the end, your projects won't just run — they'll sell your skills.

The problem this lesson solves

The Problem of the Invisible Developer. You can build working Kivy apps, but if no one can find, understand, or run them, you're invisible. The market doesn't reward code hidden in a private repo or a notebook with no context. Without a structured portfolio, you:

• Fail to demonstrate skill progression — potential employers see a random list, not a growth curve from simple UIs to complex multi-screen apps.
• Lose projects to bit rot — dependencies change, and a project without a requirements.txt won't run in a year.
• Miss opportunities — no clear path for someone to try your app means no feedback, no star, no job offer.

A portfolio for Kivy projects is not a luxury; it's the final deliverable of your learning journey. It answers the question every reviewer asks: "Can this developer ship and communicate?"

Core concept / mental model

Think of your portfolio as a curated exhibition, not a storage room. A storage room is your ~/code directory — full of half-finished experiments. An exhibition is the deliberate selection, arrangement, and labeling of your best work to tell a story.

Definitions:

• Portfolio — a collection of projects that demonstrate your range, skill, and growth.
• README — your project's front door; it tells visitors what the app does, how to run it, and why it matters.
• Project structure — the standard folders and files that make your code navigable and maintainable.

The mental model — Your portfolio is a garden. Each project is a plant. A garden isn't a pile of cut flowers; it's carefully planned beds, labeled paths, and thoughtful placement. You prune (select the best projects), fertilize (document them), and arrange for visual appeal (consistent structure). The result is something people want to walk through.

How it works step by step

Here's the high-level workflow for assembling your portfolio. It's not just "put files on GitHub" — it's a deliberate process.

Step 1: Audit your projects

List every Kivy project you've created. For each, ask:

• Does it work? (Can you run it today?)
• Does it show a unique skill? (Custom widget, ListView, animation, canvas drawing, API integration)
• Is it complete? (Has an entry point and a clear purpose)

You want 3–5 strong projects that tell a story: from beginner (basic Button/Label) to advanced (multi-screen with navigation, Crashlytics).

Step 2: Create a consistent structure

Each project folder should follow the same layout. This makes your portfolio instantly navigable.

my_kivy_app/
├── main.py
├── kivy_app.kv
├── data/
│   └── some_asset.png
├── tests/
│   └── test_main.py
├── requirements.txt
├── README.md
└── LICENSE

Step 3: Write a powerful README for each project

A README is your project's pitch. For a Kivy project, include:

• Title & short description (what does it do?)
• Screenshot / GIF (show, don't tell)
• Features (bullet list)
• Installation (brew/conda/pip commands)
• Usage (how to launch: python main.py)
• Tech stack (Kivy version, Python version)

Step 4: Link them together with a portfolio root

Create a central README.md in your GitHub profile repo (or a dedicated 'kivy-portfolio' repo) that lists all projects with one-line descriptions and links.

Pro tip: A profile README (<username>/<username>) is a public showcase. Use it to welcome visitors and present a table of contents to your best work.

Step 5: Version everything with Git

Initialize a repo for each project, commit early, and push to GitHub. Include a .gitignore for Python artifacts and your virtual environment.

Now let's see this in practice.

Hands-on walkthrough

Example 1: The minimal, reliable project skeleton

Every project in your portfolio should start with this. Here's a complete, runnable Kivy app to include as your base template.

# main.py
from kivy.app import App
from kivy.uix.boxlayout import BoxLayout
from kivy.uix.button import Button
from kivy.uix.label import Label

class RootWidget(BoxLayout):
    def __init__(self, **kwargs):
        super().__init__(**kwargs)
        label = Label(text="Welcome to My Kivy Portfolio!")
        button = Button(text="Tap Me")
        button.bind(on_press=self.on_button_press)
        self.add_widget(label)
        self.add_widget(button)

    def on_button_press(self, instance):
        instance.text = "You tapped!"

class MyPortfolioApp(App):
    def build(self):
        return RootWidget()

if __name__ == "__main__":
    MyPortfolioApp().run()

Run it with:

python main.py

Expected output: A window with a label and a button. Clicking the button changes its text. This is your 'hello world' that proves the environment works.

Example 2: The portfolio root README generator

Instead of hand-writing your central index, use a script to generate it from your project folders. This keeps it always up to date.

import os
import re
from pathlib import Path

# Define your project directories and one-line descriptions
projects = [
    ("kivy-todo-app", "A cross-platform to-do list with swipe-to-delete."),
    ("kivy-weather-widget", "Real-time weather using OpenWeatherMap API."),
    ("kivy-multi-screen-nav", "Multi-screen app with navigation drawer and custom animations."),
]

# Generate markdown table cells for the main README
def generate_links(projects):
    md = ""
    for name, desc in projects:
        md += f"| [{name}]({name}/) | {desc} |\n"
    return md

if __name__ == "__main__":
    md_links = generate_links(projects)
    readme = f"""
# My Kivy Portfolio

Welcome! Here are my Kivy mobile apps. Each project is self-contained with its own README.

| Project | Description |
|---------|-------------|
{md_links}

## How to explore

Clone a project, install its dependencies (see per-project README), and run `python main.py`.
"""
    Path("PORTFOLIO.md").write_text(readme, encoding="utf-8")
    print("Portfolio README generated: PORTFOLIO.md")

Run it:

python generate_readme.py

Expected output: a PORTFOLIO.md file with a table linking to each project.

Example 3: The polished README template

Copy this into each project's README, filling in your own details.

# Project Name

A brief description — what it does, why it's useful.

![Screenshot](screenshot.png)

## Features

- Feature 1
- Feature 2

## Getting Started

### Prerequisites

- Python 3.10+
- Kivy >= 2.2.0

### Installation

```bash
pip install kivy

Running the app

python main.py

Built With

• Kivy

License

MIT ```

Pro tip: Add a short GIF of your app in action to the README — recruiters love seeing the UI without having to run it.

Compare options / when to choose what

When assembling your portfolio, you have decisions about structure and placement. Here's a comparison to guide you.

Recommendation: For a Kivy developer, use per-project repos + a portfolio root README. It separates concerns, shows professionalism, and lets each app's README dive deep.

Troubleshooting & edge cases

Your README links are broken. Why: The path in the table might be relative to the root, but the project folder is named differently. Fix: Use the exact repository name or a relative URL like kivy-todo-app/ in the same repo.

The app doesn't run after cloning. Why: Missing dependencies — no requirements.txt or outdated versions. Fix: Always generate a requirements.txt with pip freeze > requirements.txt before pushing.

Your portfolio looks messy because of too many topics. Why: You included every experiment. Fix: Curate ruthlessly. Keep 3–5 projects that build a coherent narrative. For the rest, archive them in a private repo.

Screenshots don't load on GitHub. Why: The image files are large and/or are stored in a subdirectory. Fix: Use a relative path and keep images under 1 MB — compress them with a tool like tinypng.

Git history conflicts when you merge branch with README. Why: Edited the same file in two branches. Fix: Use a feature-branch workflow and always git pull --rebase before pushing.

What you learned & what's next

You've now learned to assemble a complete Kivy mobile project portfolio. You can audit your projects, give them a consistent structure, write a compelling README, and link them together with a generated portfolio index. You applied this in a hands-on exercise, creating a runnable base template and a README generator script. Each of these steps directly addresses the initial pain: your code is now discoverable, runnable, and tells the story of your growth.

Next lesson: the track's next step will focus on distributing your Kivy app — building a .apk with Buildozer and publishing to the Play Store. Your now-professional portfolio becomes the launchpad for public release.