Skip to content

Commit b78982e

Browse files
kpatrykkpatryk
committed
feat: Update docs, add CI documentation to document a current process
1 parent 6ae89c3 commit b78982e

4 files changed

Lines changed: 351 additions & 3 deletions

File tree

‎README.md‎

Lines changed: 19 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -112,6 +112,22 @@ Test files are located in `my_tests/` folder.
112112

113113
See `my_tests/conftest.py` for fixture definitions.
114114

115-
## 📚 References
116-
- [Copier Documentation](https://copier.readthedocs.io/en/stable/)
117-
- [pre-commit](https://pre-commit.com/)
115+
## 📚 Local Documentation
116+
117+
Project-specific guides and workflows:
118+
119+
| Topic | Location |
120+
|-------|----------|
121+
| CI/CD Pipeline | [docs/ci.md](docs/ci.md) |
122+
| Development Setup | [docs/development.md](docs/development.md) |
123+
| Template Architecture | [docs/architecture.md](docs/architecture.md) |
124+
125+
## 🔗 External References
126+
127+
For framework and tool documentation:
128+
129+
- **Copier Framework**: [Copier Documentation](https://copier.readthedocs.io/en/stable/)
130+
- **Python Packaging**: [PEP 621 - pyproject.toml](https://peps.python.org/pep-0621/)
131+
- **UV Package Manager**: [UV Documentation](https://docs.astral.sh/uv/)
132+
- **Ruff Formatter**: [Ruff Documentation](https://docs.astral.sh/ruff/)
133+
- **Pre-commit Hooks**: [pre-commit Framework](https://pre-commit.com/)

‎docs/architecture.md‎

Lines changed: 186 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,186 @@
1+
# Template Architecture
2+
3+
This document describes the structure and design of the Copier template.
4+
5+
## Overview
6+
7+
The template is built using [Copier](https://copier.readthedocs.io/), a project templating tool that uses Jinja2 for dynamic content generation.
8+
9+
## Configuration
10+
11+
### `copier.yaml`
12+
13+
The main template configuration file that defines:
14+
- **Questions**: Interactive prompts for template variables
15+
- **Conditional Files**: Using `_if_` prefix for dynamic file inclusion
16+
- **Exclusions**: Files/directories not copied to generated projects via `_exclude`
17+
- **Jinja Extensions**: Custom Jinja filters and extensions
18+
- **Tasks**: Post-generation operations (migrations, setup scripts)
19+
20+
## Template Structure
21+
22+
```
23+
├── src/{{project_name}}/ # Main source code directory (templated)
24+
│ ├── __init__.py.jinja # Package initialization
25+
│ └── main.py.jinja # Main module
26+
├── tests/ # Test directory structure (templated)
27+
│ ├── __init__.py.jinja
28+
│ └── unit/
29+
│ └── test_init.py.jinja
30+
├── pyproject.toml.jinja # Project configuration (templated)
31+
├── README.md.jinja # Project README (templated)
32+
├── Makefile.jinja # Development tasks (templated)
33+
├── .copier-answers.yml.jinja # Answers tracking (templated)
34+
├── {{ _copier_conf.answers_file }}.jinja # Answers file configuration
35+
│
36+
├── samples/ # Example data files (EXCLUDED)
37+
│ └── config-basic.yml # Sample answers file
38+
├── my_tests/ # Test suite (EXCLUDED)
39+
│ ├── conftest.py
40+
│ ├── test_core_structure.py
41+
│ ├── test_exclusions.py
42+
│ └── test_conditional_sections.py
43+
├── copier.yaml # Template configuration
44+
└── README.md # Template documentation
45+
```
46+
47+
## Excluded Directories
48+
49+
Files in these directories are **NOT** copied to generated projects:
50+
51+
- `samples/` - Example configuration and data files
52+
- `my_tests/` - Template validation tests
53+
- `.git/` - Git metadata (Copier default)
54+
- `__pycache__/` - Python cache (Copier default)
55+
56+
Exclusion is configured in `copier.yaml` via the `_exclude` key.
57+
58+
## Templating Conventions
59+
60+
### Variable Interpolation
61+
62+
Use double-brace syntax for Jinja2 variables:
63+
64+
```jinja
65+
Project: {{ project_name }}
66+
Author: {{ author_name }}
67+
Python: {{ python_version }}
68+
```
69+
70+
### Conditional Sections
71+
72+
Use `_if_` prefix to conditionally include files:
73+
74+
```
75+
file_name_if_condition.py.jinja
76+
```
77+
78+
This file is only included when the condition evaluates to `true`.
79+
80+
### File Extensions
81+
82+
- `.jinja` - Files that require template rendering
83+
- No extension - Static files copied as-is
84+
85+
Example:
86+
```
87+
README.md.jinja # Rendered with Jinja2
88+
LICENSE # Copied without processing
89+
```
90+
91+
## Testing
92+
93+
The template includes comprehensive tests in `my_tests/`:
94+
95+
| Test | Purpose |
96+
|------|---------|
97+
| `test_core_structure.py` | Validates project structure, required files, and directories |
98+
| `test_exclusions.py` | Ensures excluded files aren't rendered in generated projects |
99+
| `test_conditional_sections.py` | Tests conditional rendering based on configuration |
100+
101+
### Test Fixtures
102+
103+
Defined in `my_tests/conftest.py`:
104+
105+
- **Session-scoped fixtures**: Generate test projects once per session, reused across tests
106+
- **Module-scoped wrappers**: Provide clean API with performance optimizations
107+
- **Read-only operations**: All tests are non-mutating to enable fixture reuse
108+
109+
## Variable Types
110+
111+
Variables are defined in `copier.yaml` with type hints:
112+
113+
- **String**: Simple text values
114+
- **Boolean**: Yes/No choices
115+
- **Choice**: Dropdown selection from predefined options
116+
- **Integer**: Numeric values
117+
- **Float**: Decimal values
118+
119+
## Answer Files
120+
121+
### `.copier-answers.yml`
122+
123+
Auto-maintained file created in generated projects. Used for:
124+
- Tracking user responses
125+
- Enabling future template updates via `copier update`
126+
- Never manually edited
127+
128+
### Sample Configuration
129+
130+
`samples/config-basic.yml` provides:
131+
- Example variable values
132+
- Used with `copier copy --data-file` for non-interactive generation
133+
- Excluded from generated projects
134+
135+
## Best Practices
136+
137+
1. **Always use relative paths** in template files
138+
2. **Keep templates DRY**: Use Jinja2 includes for shared content
139+
3. **Test conditionals thoroughly**: Edge cases matter
140+
4. **Document variables**: Include helpful descriptions in `copier.yaml`
141+
5. **Version templates**: Use Git tags for reproducible generations
142+
6. **Commit before testing**: Copier uses Git to detect files
143+
7. **Keep exclusions updated**: Remove deprecated files from templates
144+
145+
## Common Tasks
146+
147+
### Add a New Template Variable
148+
149+
1. Add question in `copier.yaml`:
150+
```yaml
151+
_questions:
152+
my_variable:
153+
type: str
154+
help: "Description of this variable"
155+
```
156+
157+
2. Use in template files:
158+
```jinja
159+
{{ my_variable }}
160+
```
161+
162+
3. Add test case in `my_tests/`
163+
164+
### Create a Conditional File
165+
166+
1. Rename file with `_if_` prefix:
167+
```
168+
optional_file_if_include_feature.py.jinja
169+
```
170+
171+
2. Define condition in `copier.yaml`
172+
173+
3. Add test to `test_conditional_sections.py`
174+
175+
### Update Generated Projects
176+
177+
Users can sync with template changes:
178+
```bash
179+
copier update --answers-file .copier-answers.yml
180+
```
181+
182+
## References
183+
184+
- [Copier Documentation](https://copier.readthedocs.io/en/stable/)
185+
- [Jinja2 Template Documentation](https://jinja.palletsprojects.com/)
186+
- [Python Packaging Guide](https://packaging.python.org/)

‎docs/ci.md‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
# CI Flow (GitHub Actions)
2+
3+
This document shows the CI flow used in `.github/workflows/test.yml`.
4+
5+
```mermaid
6+
flowchart TD
7+
classDef trigger fill:#1F2937,stroke:#111827,color:#FFFFFF,font-weight:bold,stroke-width:3px;
8+
classDef checkout fill:#0369A1,stroke:#024873,color:#FFFFFF,stroke-width:2px;
9+
classDef setup fill:#10B981,stroke:#059669,color:#FFFFFF,stroke-width:2px;
10+
classDef cache fill:#F59E0B,stroke:#D97706,color:#FFFFFF,stroke-width:2px;
11+
classDef test fill:#8B5CF6,stroke:#7C3AED,color:#FFFFFF,stroke-width:2px;
12+
classDef artifact fill:#EF4444,stroke:#DC2626,color:#FFFFFF,stroke-width:2px;
13+
classDef summary fill:#6B7280,stroke:#4B5563,color:#FFFFFF,stroke-width:2px;
14+
classDef matrixItem fill:#1E293B,stroke:#0F172A,color:#FFFFFF;
15+
classDef note fill:#FEF08A,stroke:#FACC15,color:#000000,stroke-width:2px;
16+
17+
A["🚀 GitHub Actions Trigger"]:::trigger
18+
A -->|push or<br/>pull_request| Matrix
19+
20+
subgraph Matrix["🖥️ Test Matrix"]
21+
direction TB
22+
M1["ubuntu-latest<br/>Python 3.10-3.13"]:::matrixItem
23+
M2["macOS-latest<br/>Python 3.10-3.13"]:::matrixItem
24+
end
25+
26+
Matrix -->|runs in parallel| B["📥 Checkout Repository"]:::checkout
27+
B --> C["⚙️ Set up Python Environment"]:::setup
28+
C --> D["📦 Install Build Tools"]:::setup
29+
D --> E["💾 Cache UV Dependencies"]:::cache
30+
E --> F["🧪 Run Tests"]:::test
31+
F -->|conditional| G["📤 Upload Artifacts"]:::artifact
32+
G --> H["📋 Print Summary"]:::summary
33+
34+
NOTE["⚠️ Note: Strategy matrix runs jobs in parallel<br/>fail-fast: false (all jobs complete)"]:::note
35+
NOTE -.-> F
36+
```
37+
38+
## Workflow Summary
39+
40+
The CI pipeline triggers on every push and pull request, running tests across multiple OS and Python version combinations. Key features:
41+
42+
- **Parallel Testing**: Matrix strategy tests on Ubuntu and macOS with Python 3.10-3.13
43+
- **Dependency Caching**: UV dependencies are cached for faster runs
44+
- **Test Execution**: Comprehensive test suite via pytest
45+
- **Artifact Upload**: Test results and logs uploaded conditionally
46+
- **No Early Exit**: `fail-fast: false` ensures all matrix jobs complete
47+
48+
## Key Stages
49+
50+
| Stage | Purpose |
51+
|-------|---------|
52+
| 🚀 Trigger | Initiates workflow on code changes |
53+
| 📥 Checkout | Retrieves repository code |
54+
| ⚙️ Setup | Configures Python environment |
55+
| 💾 Cache | Optimizes dependency installation |
56+
| 🧪 Tests | Executes test suite |
57+
| 📤 Artifacts | Captures test results |
58+
| 📋 Summary | Reports final status |

‎docs/development.md‎

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
# Development Guide
2+
3+
This guide covers local development setup and workflow for the Copier template project.
4+
5+
## Prerequisites
6+
7+
- Python 3.10 or newer
8+
- Git
9+
- uv (recommended) or pip/pipx
10+
11+
## Quick Start
12+
13+
1. **Clone the repository:**
14+
```bash
15+
git clone https://github.com/patryk-gpl/copier-python-uv.git
16+
cd copier-python-uv
17+
```
18+
19+
2. **Install dependencies:**
20+
```bash
21+
make install
22+
```
23+
24+
3. **Run tests:**
25+
```bash
26+
make test
27+
```
28+
29+
## Development Workflow
30+
31+
### Running Tests Locally
32+
33+
Execute the full test suite:
34+
```bash
35+
make test
36+
```
37+
38+
Run specific test files:
39+
```bash
40+
make test FILE=my_tests/test_core_structure.py
41+
```
42+
43+
### Code Quality
44+
45+
Format code:
46+
```bash
47+
make format
48+
```
49+
50+
Check code style:
51+
```bash
52+
make lint
53+
```
54+
55+
## Important Notes
56+
57+
### Git Repository Requirement for Testing
58+
59+
**Copier requires Git-tracked files when using `vcs_ref="HEAD"`**
60+
61+
When running tests locally:
62+
- Ensure all template files are **committed to Git** before running tests
63+
- Copier uses Git to determine which files to include
64+
- Uncommitted files in the working directory are **ignored** by Copier
65+
66+
Before running tests:
67+
```bash
68+
git add .
69+
git commit -m "WIP: template changes"
70+
```
71+
72+
## Tools Used
73+
74+
- **uv**: Fast Python package installer and resolver
75+
- **ruff**: Fast Python linter and formatter
76+
- **pytest**: Testing framework
77+
- **copier**: Project template tool
78+
- **pre-commit**: Git hooks framework
79+
80+
## Troubleshooting
81+
82+
### UV cache issues
83+
84+
Clear and resync:
85+
```bash
86+
uv cache clean
87+
make install
88+
```

0 commit comments

Comments
 (0)