Skip to content

Commit be34db1

Browse files
bnbongbnbong
committed
[DOCS] core docs update
1 parent dfbce99 commit be34db1

File tree

5 files changed

+485
-23
lines changed

5 files changed

+485
-23
lines changed

‎CONTRIBUTING.md

Lines changed: 174 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -26,29 +26,193 @@ FastAPI-fastkit uses following stacks:
2626

2727
### Local dev configuration
2828

29-
(content will be added later)
29+
1. Clone repository:
30+
31+
```bash
32+
git clone https://github.com/bnbong/FastAPI-fastkit.git
33+
```
34+
35+
2. Set up virtual environment & Install dependencies:
36+
37+
```bash
38+
cd FastAPI-fastkit
39+
40+
python -m venv .venv
41+
source .venv/bin/activate # for Windows, use: .venv\Scripts\activate
42+
43+
pip install -r requirements.txt
44+
```
3045

3146
### Linting & Formatting
3247

33-
(content will be added later - formatter : black)
48+
Use these tools for code quality:
49+
50+
1. Black: Code formatting
51+
52+
```bash
53+
bash scripts/format.sh
54+
```
55+
56+
2. isort: Import sorting
57+
58+
```bash
59+
bash scripts/sort.sh
60+
```
61+
62+
3. mypy: Static type checking
63+
64+
```bash
65+
bash scripts/lint.sh
66+
```
67+
3468

3569
### Making commits
3670

37-
(content will be added later - include custom commit tag like '[FEAT]', '[FIX]', '[TEST]', ...)
71+
Use these tags in commit messages:
72+
73+
- [FEAT]: New feature
74+
- [FIX]: Bug fix
75+
- [DOCS]: Documentation changes
76+
- [STYLE]: Code formatting
77+
- [TEST]: Test code
78+
- [REFACTOR]: Code refactoring
79+
- [CHORE]: Build, config changes
80+
81+
Example:
82+
83+
```bash
84+
git commit -m '[FEAT] Add new FastAPI template for microservices'
85+
git commit -m '[FIX] Fix virtual environment activation in Windows'
86+
```
3887

3988
## Documentation
4089

41-
(content will be added later)
90+
Follow these documentation guidelines:
91+
92+
1. Docstring for all functions/classes (not necessary, but recommended)
93+
2. Except for translations and typographical corrections, modifications to the core [README.md](README.md), [SECURITY.md](SECURITY.md), [CONTRIBUTING.md](CONTRIBUTING.md), [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) files of the FastAPI-fastkit project itself are prohibited.
4294

4395
## Testing
4496

45-
(content will be added later)
97+
After writing new tests or modifying existing tests, run these commands to ensure the tests pass:
98+
99+
1. Run tests:
100+
101+
```bash
102+
pytest tests/
103+
```
104+
105+
2. Check coverage:
106+
107+
```bash
108+
pytest --cov=src tests/
109+
```
46110

47111
## Adding new FastAPI-based template project
48112

49-
(content will be added later)
50-
(this block will contain about dependancy settings using virtual env, project tree, file extension of all sources(must end with .py-tpl),
51-
README.md writing guide(using [PROJECT_README_TEMPLATE.md](src/fastapi_fastkit/fastapi_project_template/PROJECT_README_TEMPLATE.md) template), foldering, other third party config, etc...)
113+
When adding a new FastAPI template project, follow these guidelines:
114+
115+
### Template Structure Requirements
116+
117+
1. Directory Structure:
118+
119+
```
120+
template-name/
121+
├── src/
122+
│ ├── main.py-tpl
123+
│ ├── config/
124+
│ ├── models/
125+
│ ├── routes/
126+
│ └── utils/
127+
├── tests/
128+
├── scripts/
129+
├── requirements.txt-tpl
130+
├── setup.py-tpl
131+
└── README.md-tpl
132+
```
133+
134+
2. File Extensions:
135+
- All Python source files must use `.py-tpl` extension
136+
- Template files must include proper configuration files (.env-tpl, etc.)
137+
138+
3. Dependencies:
139+
- Include `fastapi-fastkit` in setup.py
140+
- Specify version numbers in requirements.txt
141+
- Use latest stable versions of dependencies
142+
143+
### Security Requirements
144+
145+
1. Implementation Requirements:
146+
- Environment variables management (.env)
147+
- Basic authentication system
148+
- CORS configuration
149+
- Exception handling and logging
150+
151+
2. Security Checks:
152+
- All template code must pass `inspector.py` validation
153+
- Include security middleware configurations
154+
- Follow security guidelines in SECURITY.md
155+
156+
### Documentation
157+
158+
1. README.md Requirements:
159+
- Use PROJECT_README_TEMPLATE.md format
160+
- Include comprehensive setup instructions
161+
- Document all environment variables
162+
- List all major dependencies
163+
- Provide API documentation
164+
165+
2. Code Documentation:
166+
- Include docstrings for all functions/classes
167+
- Document API endpoints
168+
- Include example usage (not necessary, but recommended)
169+
- Provide configuration explanations
170+
171+
### Testing
172+
173+
1. Required Tests:
174+
- Basic CRUD operations
175+
- Authentication/Authorization
176+
- Error handling
177+
- API endpoints
178+
- Configuration validation
179+
180+
2. Test Coverage:
181+
- Minimum 80% code coverage
182+
- Include integration tests
183+
- API testing examples
184+
185+
### Submission Process
186+
187+
1. Initial Setup:
188+
- Clone or Fork the repository
189+
- Create a new branch for your template
190+
- Follow the template structure
191+
192+
2. Development:
193+
- Implement required features
194+
- Add comprehensive tests
195+
- Document all components
196+
- Run inspector.py validation
197+
198+
3. Pre-submission Checklist:
199+
- [ ] All files use .py-tpl extension
200+
- [ ] FastAPI-fastkit dependency included
201+
- [ ] README.md follows template
202+
- [ ] Security requirements met
203+
- [ ] Tests implemented and passing
204+
- [ ] Documentation complete
205+
- [ ] inspector.py validation passes
206+
207+
4. Pull Request:
208+
- Provide detailed description
209+
- Include test results
210+
- Document any special requirements
211+
- Reference related issues
212+
213+
For more detailed information about security requirements and project guidelines, please refer to:
214+
- [SECURITY.md](SECURITY.md) for security guidelines
215+
- [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) for project principles
52216

53217
## Additional note
54218

@@ -58,9 +222,9 @@ In that section, I have my information as the manager of this project as author,
58222

59223
I emphasize that the reason I left my information in the comment section is to specify the information about the project's final director and not to increase the barriers to entry into the open source contribution of other contributors.
60224

61-
**However**, I would like to inform you that I have only the right to modify the document file itself such as .md file.
225+
**However**, I would like to inform you that I have only the right to modify the document file content itself of FastAPI-fastkit project's core documents (README.md, SECURITY.md, CODE_OF_CONDUCT.md, CONTRIBUTING.md) file.
62226

63-
If the contribution to the project includes the contribution to the document, there is a possibility that PR will be rejected.
227+
If the contribution to the project includes the document contribution except translation and typographical corrections, there is a possibility that PR will be rejected.
64228

65229
---
66230
@author bnbong bbbong9@gmail.com

‎README.md

Lines changed: 138 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
<p align="center">
2-
<img align="top" width="70%" src=".github/FastAPI-fastkit_logo/fastkit_general_logo.png" alt="FastAPI-fastkit"/>
2+
<img align="top" width="70%" src="https://bnbong.github.io/projects/img/fastkit_general_logo.png" alt="FastAPI-fastkit"/>
33
</p>
44
<p align="center">
55
<em><b>FastAPI-fastkit</b>: Fast, easy-to-use starter kit for new users of Python and FastAPI</em>
@@ -17,11 +17,146 @@
1717

1818
This project was created to speed up the configuration of the development environment needed to develop Python-based web apps for new users of Python and [FastAPI](https://github.com/fastapi/fastapi).
1919

20-
This project was inspired by the `SpringBoot initializer` of the JAVA ecosystem & Python Django's `django-admin` cli operation.
20+
This project was inspired by the `SpringBoot initializer` & Python Django's `django-admin` cli operation.
2121

2222
---
2323

24-
(other content will be updated later)
24+
## Key Features
25+
26+
- **Immediate FastAPI project creation** : Super-fast FastAPI workspace & project creation via CLI, inspired by `django-admin`feature of [Python Django](https://github.com/django/django)
27+
- **Prettier CLI outputs** : beautiful CLI experiment ([rich library](https://github.com/Textualize/rich) feature)
28+
- **Standards-based FastAPI project template** : All FastAPI-fastkit templates are based on Python standards and FastAPI's common use
29+
30+
---
31+
32+
## Installation
33+
34+
Install `FastAPI-fastkit` at your Python environment.
35+
36+
```console
37+
$ pip install FastAPI-fastkit
38+
39+
---> 100%
40+
```
41+
42+
## Usage
43+
44+
### Create a new FastAPI project workspace environment immediately
45+
46+
Create a new FastAPI project workspace with:
47+
48+
```console
49+
$ fastkit startproject
50+
Enter project name: <your-project-name>
51+
52+
Available Stacks and Dependencies:
53+
MINIMAL Stack
54+
┌──────────────┬─────────┐
55+
│ Dependency 1 │ fastapi │
56+
│ Dependency 2 │ uvicorn │
57+
└──────────────┴─────────┘
58+
59+
60+
STANDARD Stack
61+
┌──────────────┬────────────┐
62+
│ Dependency 1 │ fastapi │
63+
│ Dependency 2 │ uvicorn │
64+
│ Dependency 3 │ sqlalchemy │
65+
│ Dependency 4 │ alembic │
66+
│ Dependency 5 │ pytest │
67+
└──────────────┴────────────┘
68+
69+
70+
FULL Stack
71+
┌──────────────┬────────────────┐
72+
│ Dependency 1 │ fastapi │
73+
│ Dependency 2 │ uvicorn │
74+
│ Dependency 3 │ sqlalchemy │
75+
│ Dependency 4 │ alembic │
76+
│ Dependency 5 │ pytest │
77+
│ Dependency 6 │ redis │
78+
│ Dependency 7 │ celery │
79+
│ Dependency 8 │ docker-compose │
80+
└──────────────┴────────────────┘
81+
82+
83+
Select stack (minimal, standard, full): minimal
84+
Creating Project:
85+
new-fastapi-project
86+
┌───────────┬────────┐
87+
│ Component │ Status │
88+
│ fastapi │ ✓ │
89+
│ uvicorn │ ✓ │
90+
└───────────┴────────┘
91+
Creating virtual environment...
92+
Installing dependencies...
93+
⠙ Setting up project environment...Collecting <packages~>
94+
95+
---> 100%
96+
97+
╭─────────────────────────────────────────────────────────────────── Success ────────────────────────────────────────────────────────────────────╮
98+
│ ✨ Project '<your-project-name>' has been created successfully! │
99+
╰────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
100+
╭───────────────────────────────────────────────────────────────────── Info ─────────────────────────────────────────────────────────────────────╮
101+
│ ℹ To activate the virtual environment, run: │
102+
│ │
103+
│ source /<new-venv-path>/venv/bin/activate │
104+
╰────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
105+
```
106+
107+
This command will create a new FastAPI project workspace environment with Python virtual environment.
108+
109+
### Place a structured FastAPI project immediately
110+
111+
Place a structured FastAPI project immediately with:
112+
113+
```console
114+
$ fastkit startup
115+
Enter the project name: <your-project-name>
116+
Enter the author name: <your-name>
117+
Enter the author email: <your-email>
118+
Enter the project description: <your-project-description>
119+
Deploying FastAPI project using 'fastapi-default' template
120+
Template path:
121+
/<fastapi_fastkit-package-path>/fastapi_project_template/fastapi-defau
122+
lt
123+
124+
125+
Project Information
126+
┌──────────────┬──────────────────────────────────────────┐
127+
│ Project Name │ <your-project-name> │
128+
│ Author │ <your-name> │
129+
│ Author Email │ <your-email> │
130+
│ Description │ <your-project-description> │
131+
└──────────────┴──────────────────────────────────────────┘
132+
133+
Do you want to proceed with project creation? [y/N]: y
134+
FastAPI template project will deploy at '<your-project-path>'
135+
136+
---> 100%
137+
138+
╭─────────────────────────────────────────────────────────────────── Success ────────────────────────────────────────────────────────────────────╮
139+
│ ✨ FastAPI project '<your-project-name>' from 'fastapi-default' has been created and saved to │
140+
│ <your-project-path>! │
141+
╰────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
142+
```
143+
144+
---
145+
146+
## Significance of FastAPI-fastkit
147+
148+
FastAPI-fastkit aims to provide a fast and easy-to-use starter kit for new users of Python and FastAPI.
149+
150+
This idea was initiated with the aim of full fill to help FastAPI newcomers to learn from the beginning, which is the production significance of the FastAPI-cli package added with the [FastAPI 0.111.0 version update](https://github.com/fastapi/fastapi/releases/tag/0.111.0).
151+
152+
As one person who has been using and loving FastAPI for a long time, I wanted to develop a project that could help me a little bit to practice [the wonderful motivation](https://github.com/fastapi/fastapi/pull/11522#issuecomment-2264639417) that FastAPI developer [tiangolo](https://github.com/tiangolo) has.
25153

26154
---
155+
156+
## License
157+
158+
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
159+
160+
---
161+
27162
@author bnbong bbbong9@gmail.com

0 commit comments

Comments
 (0)