Skip to content

Commit 20a9493

Browse files
Heisenberg208Heisenberg208
committed
[SAM-260013]: feat: add Makefile for simplified commands and enhance FAQ with additional questions
1 parent 59028c9 commit 20a9493

4 files changed

Lines changed: 162 additions & 27 deletions

File tree

‎Makefile‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
.PHONY: install lint format type test run api clean
2+
3+
install:
4+
poetry install
5+
6+
lint:
7+
poetry run ruff check .
8+
poetry run black --check .
9+
poetry run mypy .
10+
11+
hooks:
12+
poetry run scripts/setup-hooks.sh
13+
format:
14+
poetry run black .
15+
poetry run ruff check --fix .
16+
17+
type:
18+
poetry run mypy .
19+
20+
test:
21+
poetry run pytest
22+
23+
run:
24+
poetry run sample dev
25+
26+
api:
27+
poetry run sample api
28+
29+
clean:
30+
find . -type d -name "__pycache__" -exec rm -rf {} +
31+
rm -rf .pytest_cache .mypy_cache dist build

‎README.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -45,7 +45,7 @@ poetry install --all-extras --with dev
4545
Or manually
4646

4747
```bash
48-
poetry install
48+
make install
4949
```
5050

5151
## How to Run
@@ -84,7 +84,7 @@ Access: <http://127.0.0.1:5000>
8484
Pre-commit hooks are enabled. If commits fail, run:
8585

8686
```bash
87-
poetry run lint
87+
make lint
8888
```
8989

9090
or run individual
@@ -146,7 +146,7 @@ these hooks will
146146

147147
```bash
148148
# Install git hooks
149-
poetry run ./scripts/setup-hooks.sh
149+
make hooks
150150
```
151151

152152
there is `.vscode/Python.code-profile` file; import this as a profile in vscode which include necessary extension for python development.

‎src/sample/utils/lint.py‎

Lines changed: 0 additions & 23 deletions
This file was deleted.

‎templates/faq.html‎

Lines changed: 128 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -30,4 +30,131 @@ <h1>Frequently Asked Questions</h1>
3030
<p>This is a useful to start the development with pre-defined template and best practices and define folder
3131
structure.</p>
3232
</details>
33-
</div>
33+
</div>
34+
<div id="technical-faq" class="faq-container">
35+
<details>
36+
<summary>Which Python version is supported?</summary>
37+
<p>
38+
Python ≥ 3.11 is required. Using lower versions may cause dependency resolution or typing issues.
39+
Verify using <code>python --version</code>.
40+
</p>
41+
</details>
42+
43+
<details>
44+
<summary>Where is the virtual environment created?</summary>
45+
<p>
46+
Poetry manages the virtual environment automatically.
47+
Run <code>poetry env info</code> to check the active environment.
48+
If virtualenvs.path is configured, it will be created in that directory.
49+
</p>
50+
</details>
51+
52+
<details>
53+
<summary>How do I add a new dependency?</summary>
54+
<p>
55+
Use Poetry only.
56+
</p>
57+
<pre><code>poetry add package-name</code></pre>
58+
<p>
59+
For dev dependencies:
60+
</p>
61+
<pre><code>poetry add --group dev package-name</code></pre>
62+
<p>
63+
Do not manually edit <code>pyproject.toml</code>.
64+
</p>
65+
</details>
66+
67+
<details>
68+
<summary>When should I regenerate poetry.lock?</summary>
69+
<p>
70+
Only when adding or upgrading dependencies.
71+
Use:
72+
</p>
73+
<pre><code>poetry lock --no-cache --regenerate</code></pre>
74+
<p>
75+
Avoid unnecessary lock file changes in pull requests.
76+
</p>
77+
</details>
78+
79+
<details>
80+
<summary>Why are environment variables not loading?</summary>
81+
<p>
82+
Ensure the <code>ENV</code> variable is set correctly:
83+
</p>
84+
<pre><code>export ENV=development</code></pre>
85+
<p>
86+
or
87+
</p>
88+
<pre><code>export ENV=production</code></pre>
89+
<p>
90+
Also confirm that corresponding <code>.env.*</code> file exists in the project root.
91+
</p>
92+
</details>
93+
94+
<details>
95+
<summary>Why is Streamlit not reflecting changes?</summary>
96+
<p>
97+
Restart the Streamlit process. If caching issues occur, clear local cache or restart the shell.
98+
</p>
99+
</details>
100+
101+
<details>
102+
<summary>Why is my commit failing?</summary>
103+
<p>
104+
Pre-commit hooks enforce linting, formatting, and type checks.
105+
Fix issues by running:
106+
</p>
107+
<pre><code>poetry run lint</code></pre>
108+
</details>
109+
110+
<details>
111+
<summary>How do I fix a corrupted virtual environment?</summary>
112+
<p>
113+
Remove and recreate the environment:
114+
</p>
115+
<pre><code>poetry env info
116+
poetry env remove &lt;env-name&gt;
117+
poetry install</code></pre>
118+
</details>
119+
120+
<details>
121+
<summary>How do I test the built package locally?</summary>
122+
<p>
123+
Build the package:
124+
</p>
125+
<pre><code>poetry build</code></pre>
126+
<p>
127+
Create a clean virtual environment and install the wheel file from <code>dist/</code>.
128+
</p>
129+
</details>
130+
<details>
131+
<summary>What if pymongo is not found?</summary>
132+
<p>
133+
MongoDB support is installed as an optional extra dependency.
134+
Install using:
135+
</p>
136+
<pre><code>pip install sample[mongo]</code></pre>
137+
<p>
138+
If using Poetry:
139+
</p>
140+
<pre><code>poetry install --extras "mongo"</code></pre>
141+
</details>
142+
143+
<details>
144+
<summary>What is the expected folder structure?</summary>
145+
<p>
146+
All source code must reside inside the <code>src/</code> directory.
147+
Business logic should not be written directly in UI or API entry files.
148+
Maintain separation between API, UI, services, and utilities.
149+
</p>
150+
</details>
151+
152+
<details>
153+
<summary>Are secrets allowed inside the repository?</summary>
154+
<p>
155+
No. Never commit secrets. Use environment variables or external secret managers.
156+
Maintain a <code>.env.example</code> file for documentation purposes.
157+
</p>
158+
</details>
159+
160+
</div>

0 commit comments

Comments
 (0)