Tài liệu xây dựng¶
Trước khi thực hiện bất kỳ thay đổi nào đối với tài liệu của BeeWare Docs Tools, bạn nên xác nhận rằng bạn có thể biên dịch được tài liệu hiện có.
Trước khi bắt đầu soạn thảo tài liệu, hãy đảm bảo rằng bạn đã thiết lập xong môi trường phát triển.
Bạn phải cài đặt trình thông dịch Python 3.13 và đảm
bảo nó có trong đường dẫn (tức là python3.13 phải khởi
chạy trình thông dịch Python 3.13).
BeeWare Docs Tools sử dụng tox để tạo tài liệu. Các lệnh tox sau đây phải
được thực thi từ cùng vị trí với tệp tox.ini, nằm trong thư mục gốc của dự án.
Xem trước tài liệu trực tiếp¶
Để hỗ trợ việc chỉnh sửa tài liệu nhanh chóng, BeeWare Docs Tools có chế độ "xem trước trực tiếp".
Bản xem trước trực tiếp sẽ được tạo ra kèm theo các cảnh báo!
Dịch vụ trực tiếp (live serve) cho phép bạn thực hiện các lần cập nhật tài liệu
một cách linh hoạt. Trong quá trình cập nhật, bạn có thể gặp phải lỗi định dạng.
Các lỗi được đánh dấu là WARNING sẽ khiến quá trình xây dựng tiêu chuẩn bị
lỗi; tuy nhiên, dịch vụ trực tiếp được cấu hình để hiển thị cảnh báo trong cửa
sổ console mà vẫn tiếp tục quá trình xây dựng. Điều này giúp bạn thực hiện các
lần cập nhật mà không cần phải khởi động lại bản xem trước trực tiếp.
Một WARNING khác với một ERROR. Nếu bạn gây ra một sự cố được coi là một
ERROR, máy chủ trực tuyến sẽ gặp sự cố và cần phải khởi động lại. Máy chủ sẽ
không khởi động lại cho đến khi sự cố WARNING được khắc phục.
Để khởi động máy chủ trực tuyến:
(venv) $ tox -e docs-live
(venv) $ tox -e docs-live
(venv) C:\...>tox -e docs-live
Quá trình này sẽ tạo tài liệu, khởi động máy chủ web để cung cấp tài liệu và theo dõi hệ thống tệp để phát hiện bất kỳ thay đổi nào đối với tệp nguồn của tài liệu.
Sau khi máy chủ được khởi động, bạn sẽ thấy nội dung tương tự như sau trong kết quả hiển thị trên bảng điều khiển:
INFO - [11:18:51] Serving on http://127.0.0.1:8000/
Mở trình duyệt và truy cập vào URL được cung cấp. Bây giờ bạn có thể bắt đầu cập nhật tài liệu. Nếu phát hiện có thay đổi, tài liệu sẽ được xây dựng lại và bất kỳ trình duyệt nào đang xem trang đã được sửa đổi sẽ tự động được làm mới.
docs-live là bước đầu tiên
Việc chạy docs-live trên máy chủ trực tiếp chỉ dành cho các lần thử nghiệm ban
đầu. Bạn luôn nên chạy bản dựng cục bộ trước khi gửi yêu cầu pull.
Bản dựng cục bộ¶
Sau khi hoàn tất quá trình lặp, bạn cần thực hiện việc biên dịch tài liệu tại máy cục bộ. Quy trình biên dịch này được thiết kế để báo lỗi nếu phát hiện bất kỳ vấn đề nào liên quan đến mã đánh dấu. Điều này giúp bạn phát hiện ra những lỗi mà bạn có thể đã bỏ sót khi kiểm tra trên máy chủ trực tuyến.
Tạo bản dựng cục bộ¶
Để tạo bản dựng cục bộ:
(venv) $ tox -e docs
(venv) $ tox -e docs
(venv) C:\...>tox -e docs
Kết quả của quá trình xây dựng này sẽ được lưu trong thư mục _build ở thư mục
gốc của dự án.
Tạo bản dựng đã dịch tại địa phương¶
Tài liệu của BeeWare Docs Tools đã được dịch sang nhiều ngôn ngữ. Các bản cập nhật đối với tài liệu tiếng Anh có thể gây ra sự cố trong các bản dịch sang các ngôn ngữ khác. Điều quan trọng là phải kiểm tra xem tất cả các bản dịch đều hoạt động bình thường trước khi gửi yêu cầu pull.
Để tạo bản dựng bao gồm tất cả các bản dịch hiện có:
(venv) $ tox -e docs-all
(venv) $ tox -e docs-all
(venv) C:\...>tox -e docs-all
Kết quả của mỗi lần biên dịch ngôn ngữ sẽ được lưu trong thư mục
_build/html/<languagecode> tương ứng, trong đó <languagecode> là mã ngôn ngữ
gồm hai hoặc năm ký tự liên quan đến ngôn ngữ cụ thể đó (ví dụ: fr cho tiếng
Pháp, it cho tiếng Ý, v.v.).
Nếu bạn phát hiện ra vấn đề với một bản dựng cụ thể, bạn có thể chạy riêng bản
dựng đó bằng cách thực thi tox -e docs-<languagecode>. Ví dụ: để chỉ xây dựng
tài liệu tiếng Pháp, hãy thực thi:
(venv) $ tox -e docs-fr
(venv) $ tox -e docs-fr
(venv) C:\...>tox -e docs-fr
Kết quả của quá trình biên dịch đơn ngôn ngữ sẽ được lưu trong thư mục _build.
Kiểm tra cú pháp tài liệu¶
Quá trình biên dịch sẽ phát hiện các lỗi Markdown, nhưng BeeWare Docs Tools thực hiện thêm một số kiểm tra về phong cách và định dạng, được gọi là "linting". Để chạy các kiểm tra lint:
(venv) $ tox -e docs-lint
(venv) $ tox -e docs-lint
(venv) C:\...>tox -e docs-lint
Điều này sẽ đảm bảo tài liệu không chứa:
- liên kết hỏng
- các từ viết sai chính tả
Nếu một cách viết đúng của một từ bị nhận diện là sai chính tả, hãy thêm từ đó
vào danh sách trong docs/spelling_wordlist. Thao tác này sẽ thêm từ đó vào từ
điển của trình kiểm tra chính tả. Khi thêm vào danh sách này, hãy lưu ý:
- Chúng tôi ưu tiên cách viết theo chuẩn Mỹ, nhưng vẫn linh hoạt chấp nhận một số thuật ngữ thông dụng đặc thù trong lĩnh vực lập trình (ví dụ: "apps") và việc biến danh từ thành động từ (ví dụ: "scrollable")
- Khi đề cập đến tên sản phẩm, cần tuân thủ quy tắc viết hoa theo quy định của sản phẩm đó. (Ví dụ: "macOS", "GTK", "pytest", "Pygame", "PyScript").
- Nếu một thuật ngữ được sử dụng "như một đoạn mã", thì nó nên được đặt trong
dấu ngoặc kép (
like this) thay vì được thêm vào từ điển.
Sau khi đã tạo thành công tài liệu, bạn đã sẵn sàng để viết tài liệu.