Thiết lập môi trường phát triển¶
Để đóng góp cho BeeWare Docs Tools, bạn cần thiết lập một môi trường phát triển.
Điều kiện tiên quyết¶
Bạn cần cài đặt các phần mềm tiên quyết sau đây.
BeeWare Docs Tools yêu cầu Python 3.10+. Bạn cũng sẽ cần một
công cụ để quản lý môi trường ảo (chẳng hạn như venv).
Bạn có thể kiểm tra phiên bản Python đã cài đặt bằng cách chạy lệnh sau:
$ python3 --version
Nếu bạn đã cài đặt nhiều phiên bản Python, bạn có thể cần thay thế python3
bằng số phiên bản cụ thể (ví dụ: python3.13)
Chúng tôi khuyên bạn nên tránh sử dụng các phiên bản Python mới ra mắt gần đây (tức là các phiên bản có số phiên bản phụ là ".0" hoặc ".1", ví dụ như 3.14.0). Lý do là các công cụ cần thiết để hỗ trợ Python trên macOS thường chậm cập nhật và thường chưa có sẵn cho các phiên bản Python ổn định mới ra mắt.
BeeWare Docs Tools yêu cầu Python 3.10+. Bạn cũng sẽ cần một
công cụ để quản lý môi trường ảo (chẳng hạn như venv).
Bạn có thể kiểm tra phiên bản Python đã cài đặt bằng cách chạy lệnh sau:
$ python3 --version
Nếu bạn đã cài đặt nhiều phiên bản Python, bạn có thể cần thay thế python3
bằng số phiên bản cụ thể (ví dụ: python3.13)
Chúng tôi khuyên bạn nên tránh sử dụng các phiên bản Python mới được phát hành gần đây (tức là các phiên bản có số phiên bản phụ là ".0" hoặc ".1", ví dụ như 3.14.0). Lý do là các công cụ cần thiết để hỗ trợ Python trên Linux thường chậm cập nhật và thường chưa có sẵn cho các phiên bản Python ổn định mới được phát hành.
BeeWare Docs Tools yêu cầu Python 3.10+. Bạn cũng sẽ cần một
công cụ để quản lý môi trường ảo (chẳng hạn như venv).
Bạn có thể kiểm tra phiên bản Python đã cài đặt bằng cách chạy lệnh sau:
C:\...>py -3 --version
Nếu bạn đã cài đặt nhiều phiên bản Python, bạn có thể cần thay thế -3 bằng số
phiên bản cụ thể (ví dụ: -python3.13)
Chúng tôi khuyên bạn nên tránh sử dụng các phiên bản Python mới được phát hành gần đây (tức là các phiên bản có số phiên bản phụ là ".0" hoặc ".1", ví dụ như 3.14.0). Lý do là các công cụ cần thiết để hỗ trợ Python trên Windows thường chậm cập nhật và thường không có sẵn cho các phiên bản Python ổn định mới được phát hành.
Thiết lập môi trường phát triển¶
Cách được khuyến nghị để thiết lập môi trường phát triển cho BeeWare Docs Tools là sử dụng một môi trường ảo, sau đó cài đặt phiên bản phát triển của BeeWare Docs Tools cùng các phụ thuộc của nó.
Sao chép kho lưu trữ BeeWare Docs Tools¶
Tiếp theo, hãy truy cập trang BeeWare Docs Tools trên GitHub, và nếu bạn chưa làm, hãy sao chép kho lưu trữ vào tài khoản của bạn. Tiếp theo, nhấp vào nút "<> Code" trên bản sao của bạn. Nếu bạn đã cài đặt ứng dụng GitHub Desktop trên máy tính, bạn có thể chọn "Open with GitHub Desktop"; nếu không, hãy sao chép URL HTTPS được cung cấp và sử dụng nó để sao chép kho lưu trữ vào máy tính của bạn bằng dòng lệnh:
Sao chép kho lưu trữ BeeWare Docs Tools, sau đó:
$ git clone https://github.com/<tên người dùng của bạn>/beeware-docs-tools.git
(thay thế bằng tên người dùng GitHub của bạn)
Sao chép kho lưu trữ BeeWare Docs Tools, sau đó:
$ git clone https://github.com/<tên người dùng của bạn>/beeware-docs-tools.git
(thay thế bằng tên người dùng GitHub của bạn)
Sao chép kho lưu trữ BeeWare Docs Tools, sau đó:
C:\...>git clone https://github.com/<tên người dùng của bạn>/beeware-docs-tools.git
(thay thế bằng tên người dùng GitHub của bạn)
Thiết lập kho lưu trữ nguồn¶
Sau khi sao chép nhánh của bạn, hãy thêm kho lưu trữ BeeWare làm kho lưu trữ từ
xa upstream. Điều này giúp bản sao cục bộ của bạn có liên kết đến kho lưu trữ
gốc, từ đó giúp việc đồng bộ hóa các bản cập nhật theo thời gian trở nên dễ dàng
hơn.
Bạn cũng cần các thẻ từ upstream để các công cụ như Toga và Briefcase có thể
xác định chính xác số phiên bản:
$ git remote add upstream https://github.com/beeware/beeware-docs-tools.git
$ git fetch --tags upstream
$ git remote add upstream https://github.com/beeware/beeware-docs-tools.git
$ git fetch --tags upstream
C:\...>git remote add upstream https://github.com/beeware/beeware-docs-tools.git
C:\...>git fetch --tags upstream
Nếu bạn muốn bản fork của mình cũng bao gồm các thẻ đó, bạn có thể đẩy chúng lên:
$ git push --tags
Điều này có thể hữu ích nếu sau này bạn tạo một bản sao mới và muốn các thẻ có sẵn từ bản phân nhánh của bạn.
Tạo một môi trường ảo¶
Để thiết lập môi trường ảo và nâng cấp pip, hãy chạy lệnh:
$ cd beeware-docs-tools
$ python3 -m venv .venv
$ source .venv/bin/activate
(.venv) $ python -m pip install -U pip
$ cd beeware-docs-tools
$ python3 -m venv .venv
$ source .venv/bin/activate
(.venv) $ python -m pip install -U pip
C:\...>cd beeware-docs-tools
C:\...>py -3 -m venv .venv
C:\...>.venv\Scripts\activate
(.venv) $ python -m pip install -U pip
Lệnh của bạn hiện đã có tiền tố (.venv) ở phía trước.
Cài đặt BeeWare Docs Tools¶
Giờ đây, khi bạn đã có mã nguồn, bạn có thể thực hiện cài đặt có thể chỉnh sửa của BeeWare Docs Tools vào môi trường phát triển của mình. Hãy chạy lệnh sau:
(.venv) $ python -m pip install -U -e . --group dev
(.venv) $ python -m pip install -U -e . --group dev
(.venv) C:\...>python -m pip install -U -e . --group dev
Bật tính năng pre-commit¶
BeeWare Docs Tools sử dụng một công cụ có tên là pre-commit để phát hiện các lỗi đơn giản và chuẩn hóa định dạng mã nguồn. Công cụ này hoạt động bằng cách cài đặt một git hook để tự động chạy một loạt các công cụ kiểm tra mã nguồn trước khi hoàn tất bất kỳ commit Git nào. Để kích hoạt pre-commit, hãy chạy lệnh:
(.venv) $ pre-commit install
pre-commit installed at .git/hooks/pre-commit
(.venv) $ pre-commit install
pre-commit installed at .git/hooks/pre-commit
(.venv) C:\...>pre-commit install
pre-commit installed at .git/hooks/pre-commit
Bây giờ bạn đã sẵn sàng để bắt đầu khám phá BeeWare Docs Tools!