A practical, beginner-friendly guide to building a clean Python project with uv, pytest, Ruff, mypy, rumdl, MkDocs, pyproject.toml, GitHub Actions, and a pull-request-based workflow with pre-commit hooks.

This repository is both a tutorial and a working example. It introduces each tool gradually and shows how the pieces fit together in a maintainable project.

• Create a new project: follow the uv quickstart.
• Run this repository locally: follow the clone and CI quickstart.
• Learn the complete workflow: start with Why This Guide Exists and follow the main learning path below.
• Browse the published guide: open the documentation site.
• Find a command or solve a problem: jump to the reference material.

By following the guide, you will learn how to:

• structure a Python project with the src/ layout,
• manage Python and dependencies with uv,
• configure the project in pyproject.toml,
• install a package in editable mode and build distributions,
• test code with pytest,
• inspect statement and branch coverage with pytest-cov,
• lint and format code with Ruff,
• check type annotations with mypy,
• lint Markdown documentation with rumdl,
• preview and validate a documentation site with MkDocs,
• publish documentation safely with GitHub Pages,
• automate fast checks with pre-commit hooks,
• run automated quality checks in GitHub Actions,
• work with branches, commits, and pull requests.

You should already know basic Python, terminal usage, Git, and GitHub. Packaging, continuous integration, and project structure are explained from the beginning.

The chapters form one step-by-step path. Start from the beginning if you want to understand why each tool and file is introduced.

1. Why this guide exists
2. Project structure
3. uv and dependency management
4. pyproject.toml
5. Testing with pytest
6. Code quality with Ruff
7. GitHub Actions and CI
8. Git, commits, branches, and pull requests
9. Common beginner mistakes
10. Building distributions
11. Static type checking with mypy
12. Test coverage with pytest-cov
13. pre-commit hooks
14. Markdown linting with rumdl
15. Documentation site with MkDocs
16. Publishing with GitHub Pages
17. Project checklist

Use these guides when you need a focused answer rather than the complete learning path.

• uv quickstart
• Clone and CI quickstart
• From script to project

• Command cheatsheet
• Glossary
• Common questions
• Troubleshooting
• Reading GitHub Actions logs

• Contributing guidelines
• Example pull request
• Reviewing Markdown changes

• Project roadmap

The repository contains a deliberately small package in src/text_toolkit/. It keeps the domain simple so the guide can focus on project structure, tooling, tests, packaging, and CI.

modern-python-project-guide/
├── .github/
│   ├── ISSUE_TEMPLATE/
│   └── workflows/
├── .pre-commit-config.yaml
├── docs/
│   ├── index.md
│   └── ...
├── src/
│   └── text_toolkit/
├── tests/
├── CONTRIBUTING.md
├── README.md
├── mkdocs.yml
├── pyproject.toml
└── uv.lock

Clone the repository and install the project environment:

git clone https://github.com/michalmaj/modern-python-project-guide.git
cd modern-python-project-guide
uv sync

Run the same quality checks used by CI:

uv run ruff check .
uv run ruff format --check .
uv run rumdl check .
uv run mkdocs build --strict
uv run pytest --cov=text_toolkit --cov-report=term-missing
uv run mypy
uv build --no-sources

Preview the documentation site separately with:

uv run mkdocs serve

For explanations and expected results, use the clone and CI quickstart.

This guide is ready to be tested with students and other learners. You do not need to propose a solution or write code to help improve it.

• Share your learning experience with the learning feedback form.
• Report an incorrect instruction, broken command, or site problem with the problem report form.
• Browse existing issues before reporting the same problem again.

Small, focused improvements are welcome. Read CONTRIBUTING.md before opening a pull request.

This project is available under the MIT License.