Skip to content

Commit b204f17

Browse files
bnbongbnbong
committed
[DOCS] update documents
1 parent 0a83f2f commit b204f17

File tree

11 files changed

+666
-203
lines changed

11 files changed

+666
-203
lines changed

‎CONTRIBUTING.md

Lines changed: 54 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -273,17 +273,61 @@ template-name/
273273

274274
### Testing
275275

276-
1. Required Tests:
277-
- Basic CRUD operations
278-
- Authentication/Authorization
276+
FastAPI-fastkit includes **automated template testing** that provides comprehensive validation:
277+
278+
#### ✅ Automatic Template Testing
279+
280+
**Zero Configuration Required:**
281+
- 🚀 New templates are **automatically discovered** and tested
282+
- ⚡ No manual test file creation needed
283+
- 🛡️ Consistent quality standards applied
284+
285+
**Comprehensive Test Coverage:**
286+
- ✅ **Project Creation**: Template copying and metadata injection
287+
- ✅ **Package Manager Support**: UV, PDM, Poetry, and PIP compatibility
288+
- ✅ **Virtual Environment**: Creation and dependency installation
289+
- ✅ **Project Structure**: File and directory validation
290+
- ✅ **FastAPI Integration**: Project identification and functionality
291+
292+
**Test Execution:**
293+
```bash
294+
# Test all templates automatically
295+
$ pytest tests/test_templates/test_all_templates.py -v
296+
297+
# Test your specific template
298+
$ pytest tests/test_templates/test_all_templates.py::TestAllTemplates::test_template_creation[your-template-name] -v
299+
300+
# Test with PDM environment
301+
$ pdm run pytest tests/test_templates/test_all_templates.py -v
302+
```
303+
304+
#### ✅ Template-Specific Testing
305+
306+
While basic functionality is automatically tested, you should include template-specific tests:
307+
308+
1. **Required Template Tests:**
309+
- Basic CRUD operations (if applicable)
310+
- Authentication/Authorization (if implemented)
279311
- Error handling
280312
- API endpoints
281313
- Configuration validation
282314

283-
2. Test Coverage:
284-
- Minimum 80% code coverage
285-
- Include integration tests
286-
- API testing examples
315+
2. **Test Coverage Goals:**
316+
- Minimum 80% code coverage for template-specific logic
317+
- Include integration tests for external services
318+
- API testing examples in template documentation
319+
320+
#### ✅ Package Manager Testing
321+
322+
Test your template with all supported package managers:
323+
324+
```bash
325+
# Test with different package managers
326+
$ fastkit startdemo your-template-name --package-manager uv
327+
$ fastkit startdemo your-template-name --package-manager pdm
328+
$ fastkit startdemo your-template-name --package-manager poetry
329+
$ fastkit startdemo your-template-name --package-manager pip
330+
```
287331

288332
### Submission Process
289333

@@ -313,10 +357,12 @@ template-name/
313357
- [ ] All files use .py-tpl extension
314358
- [ ] FastAPI-fastkit dependency included
315359
- [ ] Security requirements met
316-
- [ ] Tests implemented and passing
317360
- [ ] Documentation complete
318361
- [ ] inspector.py validation passes
319362
- [ ] All make dev-check tests pass
363+
- [ ] **Automatic template tests pass** (new templates tested automatically)
364+
- [ ] **Package manager compatibility verified** (tested with UV, PDM, Poetry, PIP)
365+
- [ ] **Template-specific functionality tested** (if applicable)
320366

321367
4. **Pull Request:**
322368
- Provide detailed description

‎README.md

Lines changed: 40 additions & 188 deletions
Original file line numberDiff line numberDiff line change
@@ -26,219 +26,66 @@ This project was inspired by the `SpringBoot initializer` & Python Django's `dja
2626
- **📋 Standards-based FastAPI project templates** : All FastAPI-fastkit templates are based on Python standards and FastAPI's common use patterns
2727
- **🔍 Automated template quality assurance** : Weekly automated testing ensures all templates remain functional and up-to-date
2828
- **🚀 Multiple project templates** : Choose from various pre-configured templates for different use cases (async CRUD, Docker, PostgreSQL, etc.)
29+
- **📦 Multiple package manager support** : Choose your preferred Python package manager (pip, uv, pdm, poetry) for dependency management
2930

3031
## Installation
3132

3233
Install `FastAPI-fastkit` at your Python environment.
3334

3435
```console
3536
$ pip install FastAPI-fastkit
36-
---> 100%
3737
```
3838

3939

4040
## Usage
4141

42-
### Create a new FastAPI project workspace environment immediately
43-
44-
You can now start new FastAPI project really fast with FastAPI-fastkit!
45-
46-
Create a new FastAPI project workspace immediately with:
42+
- Global options
43+
- `--help`: Show help
44+
- `--version`: Show version
45+
- `--debug/--no-debug`: Toggle debug mode
4746

47+
### Create a new FastAPI project
4848
```console
49-
$ fastkit init
50-
Enter the project name: my-awesome-project
51-
Enter the author name: John Doe
52-
Enter the author email: john@example.com
53-
Enter the project description: My awesome FastAPI project
54-
55-
Project Information
56-
┌──────────────┬────────────────────────────┐
57-
│ Project Name │ my-awesome-project │
58-
│ Author │ John Doe │
59-
│ Author Email │ john@example.com │
60-
│ Description │ My awesome FastAPI project │
61-
└──────────────┴────────────────────────────┘
62-
63-
Available Stacks and Dependencies:
64-
MINIMAL Stack
65-
┌──────────────┬───────────────────┐
66-
│ Dependency 1 │ fastapi │
67-
│ Dependency 2 │ uvicorn │
68-
│ Dependency 3 │ pydantic │
69-
│ Dependency 4 │ pydantic-settings │
70-
└──────────────┴───────────────────┘
71-
72-
STANDARD Stack
73-
┌──────────────┬───────────────────┐
74-
│ Dependency 1 │ fastapi │
75-
│ Dependency 2 │ uvicorn │
76-
│ Dependency 3 │ sqlalchemy │
77-
│ Dependency 4 │ alembic │
78-
│ Dependency 5 │ pytest │
79-
│ Dependency 6 │ pydantic │
80-
│ Dependency 7 │ pydantic-settings │
81-
└──────────────┴───────────────────┘
82-
83-
FULL Stack
84-
┌──────────────┬───────────────────┐
85-
│ Dependency 1 │ fastapi │
86-
│ Dependency 2 │ uvicorn │
87-
│ Dependency 3 │ sqlalchemy │
88-
│ Dependency 4 │ alembic │
89-
│ Dependency 5 │ pytest │
90-
│ Dependency 6 │ redis │
91-
│ Dependency 7 │ celery │
92-
│ Dependency 8 │ pydantic │
93-
│ Dependency 9 │ pydantic-settings │
94-
└──────────────┴───────────────────┘
95-
96-
Select stack (minimal, standard, full): minimal
97-
Do you want to proceed with project creation? [y/N]: y
98-
FastAPI project will deploy at '~your-project-path~'
99-
100-
╭──────────────────────── Info ────────────────────────╮
101-
│ ℹ Injected metadata into setup.py │
102-
╰──────────────────────────────────────────────────────╯
103-
╭──────────────────────── Info ────────────────────────╮
104-
│ ℹ Injected metadata into config file │
105-
╰──────────────────────────────────────────────────────╯
106-
107-
Creating Project:
108-
my-awesome-project
109-
┌───────────────────┬───────────┐
110-
│ Component │ Collected │
111-
│ fastapi │ ✓ │
112-
│ uvicorn │ ✓ │
113-
│ pydantic │ ✓ │
114-
│ pydantic-settings │ ✓ │
115-
└───────────────────┴───────────┘
116-
117-
Creating virtual environment...
118-
119-
╭──────────────────────── Info ────────────────────────╮
120-
│ ℹ venv created at │
121-
│ ~your-project-path~/my-awesome-project/.venv │
122-
│ To activate the virtual environment, run: │
123-
│ │
124-
│ source │
125-
│ ~your-project-path~/my-awesome-project/.venv/bin/act │
126-
│ ivate │
127-
╰──────────────────────────────────────────────────────╯
128-
129-
Installing dependencies...
130-
⠙ Setting up project environment...Collecting <packages~>
131-
132-
---> 100%
133-
134-
╭─────────────────────── Success ───────────────────────╮
135-
│ ✨ Dependencies installed successfully │
136-
╰───────────────────────────────────────────────────────╯
137-
╭─────────────────────── Success ───────────────────────╮
138-
│ ✨ FastAPI project 'my-awesome-project' has been │
139-
│ created successfully and saved to │
140-
│ ~your-project-path~! │
141-
╰───────────────────────────────────────────────────────╯
142-
╭──────────────────────── Info ────────────────────────╮
143-
│ ℹ To start your project, run 'fastkit runserver' at │
144-
│ newly created FastAPI project directory │
145-
╰──────────────────────────────────────────────────────╯
49+
fastkit init [OPTIONS]
14650
```
51+
- What it does: Scaffolds an empty FastAPI project, creates a virtual environment, installs dependencies
52+
- Key options:
53+
- `--project-name`, `--author`, `--author-email`, `--description`
54+
- `--package-manager` [pip|uv|pdm|poetry]
55+
- Stack selection: `minimal` | `standard` | `full` (interactive)
14756

148-
This command will create a new FastAPI project workspace environment with Python virtual environment.
149-
150-
### Add a new route to the FastAPI project
151-
152-
`FastAPI-fastkit` makes it easy to expand your FastAPI project.
153-
154-
Add a new route endpoint to your FastAPI project with:
155-
57+
### Create a project from a template
15658
```console
157-
$ fastkit addroute my-awesome-project user
158-
Adding New Route
159-
┌──────────────────┬──────────────────────────────────────────┐
160-
│ Project │ my-awesome-project │
161-
│ Route Name │ user │
162-
│ Target Directory │ ~your-project-path~ │
163-
└──────────────────┴──────────────────────────────────────────┘
164-
165-
Do you want to add route 'user' to project 'my-awesome-project'? [Y/n]: y
166-
167-
╭──────────────────────── Info ────────────────────────╮
168-
│ ℹ Updated main.py to include the API router │
169-
╰──────────────────────────────────────────────────────╯
170-
╭─────────────────────── Success ───────────────────────╮
171-
│ ✨ Successfully added new route 'user' to project │
172-
│ `my-awesome-project` │
173-
╰───────────────────────────────────────────────────────╯
59+
fastkit startdemo [TEMPLATE] [OPTIONS]
17460
```
61+
- What it does: Creates a project from a template (e.g., `fastapi-default`) and installs dependencies
62+
- Key options:
63+
- `--project-name`, `--author`, `--author-email`, `--description`
64+
- `--package-manager` [pip|uv|pdm|poetry]
65+
- Tip: List available templates with `fastkit list-templates`
17566

176-
### Place a structured FastAPI demo project immediately
177-
178-
You can also start with a structured FastAPI demo project.
179-
180-
Demo projects are consist of various tech stacks with simple item CRUD endpoints implemented.
181-
182-
Place a structured FastAPI demo project immediately with:
67+
### Add a new route
68+
```console
69+
fastkit addroute <project_name> <route_name>
70+
```
71+
- What it does: Adds a new API route to the specified project
18372

73+
### Run the development server
18474
```console
185-
$ fastkit startdemo
186-
Enter the project name: my-awesome-demo
187-
Enter the author name: John Doe
188-
Enter the author email: john@example.com
189-
Enter the project description: My awesome FastAPI demo
190-
Deploying FastAPI project using 'fastapi-default' template
191-
Template path:
192-
/~fastapi_fastkit-package-path~/fastapi_project_template/fastapi-default
193-
194-
Project Information
195-
┌──────────────┬─────────────────────────┐
196-
│ Project Name │ my-awesome-demo │
197-
│ Author │ John Doe │
198-
│ Author Email │ john@example.com │
199-
│ Description │ My awesome FastAPI demo │
200-
└──────────────┴─────────────────────────┘
201-
202-
Template Dependencies
203-
┌──────────────┬───────────────────┐
204-
│ Dependency 1 │ fastapi │
205-
│ Dependency 2 │ uvicorn │
206-
│ Dependency 3 │ pydantic │
207-
│ Dependency 4 │ pydantic-settings │
208-
│ Dependency 5 │ python-dotenv │
209-
└──────────────┴───────────────────┘
210-
211-
Do you want to proceed with project creation? [y/N]: y
212-
FastAPI template project will deploy at '~your-project-path~'
213-
214-
---> 100%
215-
216-
╭─────────────────────── Success ───────────────────────╮
217-
│ ✨ Dependencies installed successfully │
218-
╰───────────────────────────────────────────────────────╯
219-
╭─────────────────────── Success ───────────────────────╮
220-
│ ✨ FastAPI project 'my-awesome-demo' from │
221-
│ 'fastapi-default' has been created and saved to │
222-
│ ~your-project-path~! │
223-
╰───────────────────────────────────────────────────────╯
75+
fastkit runserver [OPTIONS]
22476
```
77+
- What it does: Starts the uvicorn development server
78+
- Key options:
79+
- `--host`, `--port`, `--reload/--no-reload`, `--workers`
22580

226-
To view the list of available FastAPI demos, check with:
81+
### List templates
82+
```console
83+
fastkit list-templates
84+
```
22785

86+
### Delete a project
22887
```console
229-
$ fastkit list-templates
230-
Available Templates
231-
┌─────────────────────────┬───────────────────────────────────┐
232-
│ fastapi-custom-response │ Async Item Management API with │
233-
│ │ Custom Response System │
234-
│ fastapi-dockerized │ Dockerized FastAPI Item │
235-
│ │ Management API │
236-
│ fastapi-empty │ No description │
237-
│ fastapi-async-crud │ Async Item Management API Server │
238-
│ fastapi-psql-orm │ Dockerized FastAPI Item │
239-
│ │ Management API with PostgreSQL │
240-
│ fastapi-default │ Simple FastAPI Project │
241-
└─────────────────────────┴───────────────────────────────────┘
88+
fastkit deleteproject <project_name>
24289
```
24390

24491
## Documentation
@@ -254,6 +101,9 @@ For comprehensive guides and detailed usage instructions, visit our documentatio
254101

255102
We welcome contributions from the community! FastAPI-fastkit is designed to help newcomers to Python and FastAPI, and your contributions can make a significant impact.
256103

104+
<details>
105+
<summary><b>Contributing Guide</b></summary>
106+
257107
### Quick Start for Contributors
258108

259109
1. **Fork and clone the repository:**
@@ -288,6 +138,8 @@ For detailed contribution guidelines, development setup, and project standards,
288138
- **[CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)** - Project principles and community standards
289139
- **[SECURITY.md](SECURITY.md)** - Security guidelines and reporting
290140

141+
</details>
142+
291143
## Significance of FastAPI-fastkit
292144

293145
FastAPI-fastkit aims to provide a fast and easy-to-use starter kit for new users of Python and FastAPI.

0 commit comments

Comments
 (0)