docs: better guidance to use

check-phat-nguoi · Jan 15, 2025 · 164f7be · 164f7be
1 parent e48a9dd
commit 164f7be
Show file tree

Hide file tree

Showing 13 changed files with 98 additions and 54 deletions.
diff --git a/README.md b/README.md
@@ -1,17 +1,11 @@
 ![pre-commit status](https://img.shields.io/github/actions/workflow/status/NTGNguyen/check-phat-nguoi/pre-commit.yml?style=for-the-badge&label=pre%20commit&branch=main&logo=precommit)
+![codeql status](https://img.shields.io/github/actions/workflow/status/NTGNguyen/check-phat-nguoi/codeql.yml?style=for-the-badge&label=codeql&branch=main)
+[![GPL 3.0](https://img.shields.io/badge/GP_3.0-blue?style=for-the-badge&label=license)](./LICENSE)
 [![wakatime](https://wakatime.com/badge/github/NTGNguyen/check-phat-nguoi.svg?style=for-the-badge)](https://wakatime.com/badge/github/NTGNguyen/check-phat-nguoi)
 
-> [!WARNING]
->
-> Work in progress!
+Tool kiểm tra phạt nguội cho phương tiện giao thông của bạn. Hỗ trợ notify đến các nền tảng Telegram, Discord...
 
-Go to website <https://ntgnguyen.github.io/check-phat-nguoi/> for documentation
-
----
-
-### LICENSE
-
-[GNU GPL v3.0](./LICENSE)
+[Documentation][doc-website]
 
 ---
 
@@ -24,3 +18,5 @@ Go to website <https://ntgnguyen.github.io/check-phat-nguoi/> for documentation
    <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=NTGNguyen/check-phat-nguoi&type=Date" />
  </picture>
 </a>
+
+[doc-website]: https://ntgnguyen.github.io/check-phat-nguoi/
diff --git a/docs/dev/checkphatnguoi_vn.md → docs/dev/apis/checkphatnguoi_vn.md b/docs/dev/checkphatnguoi_vn.md → docs/dev/apis/checkphatnguoi_vn.md
diff --git a/docs/dev/csgt_vn.md → docs/dev/apis/csgt_vn.md b/docs/dev/csgt_vn.md → docs/dev/apis/csgt_vn.md
diff --git a/docs/dev/phatnguoi_vn.md → docs/dev/apis/phatnguoi_vn.md b/docs/dev/phatnguoi_vn.md → docs/dev/apis/phatnguoi_vn.md
diff --git a/docs/dev/setup.md b/docs/dev/setup.md
@@ -28,16 +28,3 @@ just w
 ```sh
 just wb
 ```
-
-# Test on production with python 3.10
-
-```sh
-uv python install 3.10
-uv venv .venv-3.10 -p 3.10
-.venv/Scripts/activate # or "source .venv/bin/active" on Linux
-pip install -e . -r ./requirements.txt
-check-phat-nguoi
-```
-
-???+note
-Can export var env `VIRTUAL_ENV=.venv-3.10`
diff --git a/docs/index.md b/docs/index.md
@@ -1,3 +1,3 @@
 # Check phạt nguội
 
-Tool kiểm tra phạt nguội cho phương tiện giao thông của bạn. Hỗ trợ notify đến các nền tảng Telegram, Discord...
+Tool kiểm tra phạt nguội cho phương tiện giao thông của bạn từ nhiều api khác nhau. Hỗ trợ notify đến các nền tảng Telegram, Discord...
diff --git a/docs/usage/from-source/pip.md b/docs/usage/from-source/pip.md
@@ -6,17 +6,15 @@
 
 ---
 
-## Cài đặt dependencies
-
-### Thiết lập môi trường ảo
+## Thiết lập môi trường ảo
 
-#### Tạo môi trường ảo
+### Tạo môi trường ảo
 
 ```sh
 python -m venv .venv
 ```
 
-#### Kích hoạt môi trường ảo
+### Kích hoạt môi trường ảo
 
 === "Windows"
 
@@ -30,7 +28,9 @@ python -m venv .venv
     source .venv/bin/activate
     ```
 
-#### Cài đặt dependencies
+---
+
+## Cài đặt dependencies
 
 ```sh
 pip install -r requirements/requirements.txt

diff --git a/docs/usage/from-source/uv-just.md b/docs/usage/from-source/uv-just.md
@@ -8,16 +8,20 @@
 
 - [just](https://github.com/casey/just)
 
-## Chạy chương trình
+---
+
+## Thiết lập môi trường và dependencies
 
 ```sh
-just
+just rpe # (1)
 ```
 
-???+ info
+1. `rpe` = `restore-production-env`
 
-    Just sẽ tự thiết lập môi trường và restore dependencies trước khi chạy.
+---
 
-???+ danger
+## Chạy chương trình
 
-    Just restore tất cả các dependencies khiến môi trường nặng
+```sh
+just
+```
diff --git a/docs/usage/from-source/uv.md b/docs/usage/from-source/uv.md
@@ -4,16 +4,48 @@
 
 - [uv](https://github.com/astral-sh/uv)
 
+---
+
 ## Thiết lập môi trường và dependencies
 
 ```sh
 uv sync --no-dev
 ```
 
+??? info
+
+    uv sẽ tự động cài đặt phiên bản python phù hợp và cài đặt dependencies vào môi trường ảo
+
+---
+
 ## Chạy chương trình
 
-```sh
-uv run check-phat-nguoi # (1)
-```
+=== "uv run"
+
+    ```sh
+    uv run check-phat-nguoi # (1)
+    ```
+
+    1. Có thể thêm arg `--frozen` để không mutate lock file
+
+=== "actived venv"
+
+    Kích hoạt môi trường ảo
+
+    === "Windows"
+
+        ```powershell
+        .venv\Scripts\activate
+        ```
+
+    === "Unix / MacOS"
+
+        ```sh
+        source .venv/bin/activate
+        ```
+
+    Chạy chương trình
 
-1. Có thể thêm arg `--frozen` để không mutate lock file
+    ```sh
+    check-phat-nguoi
+    ```
diff --git a/docs/usage/index.md b/docs/usage/index.md
@@ -9,5 +9,23 @@
 
 !!! warning
 
-    - Hiện tại API từ csgt.vn không đảm bảo hoạt động.
-    - checkphatnguoi.vn không cho truy cập từ IP nước ngoài? (Ảnh hưởng github action)
+    - API `checkphatnguoi.vn` không cho truy cập từ IP nước ngoài? (Ảnh hưởng github action)
+    - API `csgt.vn` không đảm bảo hoạt động ổn định vì tesseract giải captcha có tỉ lệ sai, cũng như máy chủ `csgt.vn` không đảm bảo đáp ứng. Vì thế không khuyến khích sử dụng API này.
+
+---
+
+## Thiết lập file config
+
+!!! note ""
+
+    Thiết lập file config trước khi chạy chương trình. Xem tại [thiết lập file config](./setup-config.md).
+
+---
+
+## Cài đặt
+
+- [Từ mã nguồn](./from-source/index.md)
+
+!!! info
+
+    Hiện repo chưa cung cấp file thực thi nên chỉ có thể chạy từ mã nguồn
diff --git a/docs/usage/setup-config.md b/docs/usage/setup-config.md
@@ -1,11 +1,11 @@
 # Thiết lập file config
 
-Thiết lập file `config.json` (1)
+Thiết lập file `config.json` tại nơi đang đứng _(Nơi gọi chạy chương trình)_ (1)
 { .annotate }
 
 1.  Hoặc
     - `check-phat-nguoi.config.json` tại nơi đang đứng
-    - `~/check-phat-nguoi.config.json`
+    - `~/check-phat-nguoi.config.json` _(tại home)_
 
 !!! info
 

diff --git a/justfile b/justfile
@@ -4,21 +4,26 @@ alias s := gen-schemas
 alias w := web-dev
 alias wb := build-web
 alias p := precommit-run-all
+alias re := restore-dev-env
+alias rpe := restore-production-env
 
-restore-env:
+restore-production-env:
+  [ -d '.venv' ] || uv sync --frozen --no-dev
+
+restore-dev-env:
   [ -d '.venv' ] || (uv sync --frozen --all-groups && uv run pre-commit install)
 
-run-check-phat-nguoi: restore-env
+run-check-phat-nguoi: restore-dev-env
   uv run check-phat-nguoi --frozen
 
-gen-schemas: restore-env
+gen-schemas: restore-dev-env
   uv run generate-schemas --frozen
 
-web-dev: restore-env
+web-dev: restore-dev-env
   rm ./site/ -rf || true
   uv run mkdocs serve
 
-build-web: restore-env
+build-web: restore-dev-env
   rm ./site/ -rf || true
   uv run mkdocs build
   rm ./site/schemas/ -rf || true
@@ -27,8 +32,8 @@ build-web: restore-env
   cp ./schemas/* ./site/schemas
   uv run generate-schema-doc --config-file jsfh-conf.yaml ./site/schemas/ ./site/schemas/
 
-clean: restore-env
+clean: restore-dev-env
   uvx cleanpy@0.5.1 .
 
-precommit-run-all: restore-env
+precommit-run-all: restore-dev-env
   uvx run pre-commit run -a
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -22,9 +22,10 @@ nav:
   - 'Config schema': 'https://ntgnguyen.github.io/check-phat-nguoi/schemas/config.html'
   - 'Development':
       - dev/setup.md
-      - dev/csgt_vn.md
-      - dev/checkphatnguoi_vn.md
-      - dev/phatnguoi_vn.md
+      - 'API':
+          - dev/apis/csgt_vn.md
+          - dev/apis/checkphatnguoi_vn.md
+          - dev/apis/phatnguoi_vn.md
   - 'Khác':
       - other/references.md
       - other/disclaimer.md
@@ -103,3 +104,4 @@ extra:
   analytics:
     provider: google
     property: G-0GRV2FG8QZ
+  generator: false