Bỏ qua

Hướng dẫn phong cách biên soạn tài liệu

Hướng dẫn này bao gồm thông tin về phong cách được mong đợi, cú pháp đặc thù của MkDocs, các công cụ cần thiết và việc dịch tài liệu, liên quan đến việc viết nội dung mới và dịch nội dung hiện có.

Phong cách chung

  • Chỉ nên viết hoa chữ cái đầu tiên của các tiêu đề và tên.
  • 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").
  • Cách viết của từ "artefact" và "artefacts" như đã nêu.
  • Chúng tôi sử dụng một khoảng trắng sau dấu chấm.
  • Chúng tôi sử dụng một dấu gạch ngang đơn được bao quanh bởi các khoảng trắng để làm dấu gạch ngang dài (hoặc ký tự HTML —).
  • 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 "dưới dạng mã", thì nó nên được trích dẫn dưới dạng mã nhúng bằng cách bao quanh nó bằng dấu gạch chéo đơn, thay vì được thêm vào từ điển.
  • Chúng tôi tránh sử dụng các từ như "chỉ cần", "chỉ" hoặc "dễ dàng" khi mô tả các thao tác mà người dùng cần thực hiện. Những từ này có thể bị hiểu là mang tính miệt thị, đặc biệt là khi người dùng đang gặp khó khăn.

Thông tin tham chiếu chéo

Bạn nên tham chiếu chéo nội dung trong tài liệu bất cứ khi nào có thể. Phần này trình bày các cách khác nhau để thực hiện việc đó, mỗi cách đều dựa trên loại thông tin được tham chiếu.

MkDocs hiển thị các liên kết được định dạng theo chuẩn Markdown. Các liên kết web được định dạng theo chuẩn Markdown như sau:

[Nội dung liên kết](https://example.com/)

Bạn cũng có thể sử dụng định dạng này để liên kết đến một tệp tin cục bộ:

[Văn bản liên kết](path/to/file.md)

Để trích dẫn các phần cụ thể trong tệp hoặc tài liệu API, bạn cần sử dụng định dạng liên kết tham chiếu của MkDocs.

Điểm neo Markdown tùy chỉnh và tham chiếu chéo nội dung

Markdown tạo các liên kết neo cho tất cả các tiêu đề (bất kỳ nội dung nào nằm trên một dòng duy nhất và bắt đầu bằng từ một đến sáu ký hiệu #), dựa trên nội dung của tiêu đề đó. Ví dụ, liên kết neo được tạo cho phần này là custom-markdown-anchors-and-content-cross---referencing. Tuy nhiên, do cách thức hoạt động của hệ thống dịch thuật của chúng tôi, bất cứ khi nào một tiêu đề phần được trích dẫn, nó phải có một liên kết neo tùy chỉnh.

MkDocs hỗ trợ hiển thị cú pháp liên kết tham chiếu, cho phép bạn liên kết đến các thành phần khác nhau trong tài liệu bằng cách sử dụng liên kết Markdown đã được điều chỉnh. Điều này bao gồm việc liên kết đến, trong số những thứ khác, các tiêu đề Markdown tùy chỉnh và các điểm neo văn bản.

Các liên kết tham khảo trong MkDocs là những liên kết được định dạng như sau:

[Nội dung liên kết][link-target]

Yêu cầu phải có tiêu đề tùy chỉnh và các liên kết nội dung

Bất kỳ phần tiêu đề hoặc nội dung nào được trích dẫn trong nội dung văn bản thông qua liên kết tham chiếu MkDocs trong tài liệu BeeWare phải được gắn một điểm neo tùy chỉnh. Nếu không, các liên kết có thể bị hỏng khi nội dung tiêu đề được dịch.

Nếu bạn cần liên kết đến một điểm neo trong tiêu đề, bạn sẽ cần tạo một điểm neo tùy chỉnh cho nội dung mong muốn. Cú pháp chung để thiết lập một điểm neo tùy chỉnh như sau:

# Tiêu đề { #anchor-name }

Ví dụ, để tùy chỉnh liên kết cho phần này thành custom-anchors, bạn cần sử dụng định dạng sau:

## Các liên kết Markdown tùy chỉnh { #custom-anchors }

Bạn cũng có thể tạo liên kết neo trên các nội dung chung, bao gồm văn bản và khối mã. Cú pháp định dạng sau đây, kèm theo các dòng mới ở trên và dưới, cần được đặt phía trên nội dung mà bạn muốn liên kết:

Nội dung ở trên.

[](){ #anchor-name }

Nội dung ở dưới, hiện đã được gắn với điểm neo ở trên.

Sau khi các điểm neo tùy chỉnh được tạo, bạn có thể liên kết đến chúng từ trong cùng một tài liệu hoặc từ các phần khác của tài liệu.

Markdown tiêu chuẩn được sử dụng để tạo liên kết đến một điểm neo trong cùng một tệp, được định dạng như sau:

[Nội dung liên kết](#anchor-name)

Để tạo liên kết đến một điểm neo trong một tài liệu khác, hãy sử dụng kiểu liên kết tham chiếu của MkDocs, được định dạng như sau:

[Nội dung liên kết][anchor-name]

Các liên kết tham khảo API

Tính năng liên kết tham chiếu của MkDocs cũng hỗ trợ liên kết chéo đến tài liệu API, bao gồm các lớp, phương thức lớp hoặc thuộc tính đã được tài liệu hóa, cũng như các tham chiếu đến tài liệu bên ngoài cụ thể.

Có nhiều cách để liên kết đến một lớp đã được tài liệu hóa, hoặc một phương thức hay thuộc tính của lớp, bất kể bạn đang liên kết từ cùng một tệp hay từ một tệp riêng biệt. Khi liên kết đến các lớp, v.v., bạn phải bao gồm các dấu gạch chéo ngược trong cặp dấu ngoặc vuông đầu tiên để hiển thị tên dưới dạng mã nội tuyến. Chỉ khi bạn sử dụng văn bản tùy chỉnh không cần hiển thị dưới dạng mã nội tuyến thì mới không cần các dấu gạch chéo ngược này. Không bao giờ được bao gồm dấu gạch chéo ngược trong cặp dấu ngoặc vuông thứ hai.

Khi hiển thị không gian tên cùng với liên kết đến một lớp, định dạng sẽ như sau:

[`module.ClassName`][]

Việc liên kết đến một lớp trong khi chỉ hiển thị tên lớp được định dạng như sau:

[`ClassName`][module.ClassName]

Các thuộc tính giống như trên, bao gồm cả tên thuộc tính. Phần sau đây hiển thị không gian tên:

[`module.ClassName.attributename`][]

Cũng giống như với các lớp, việc hiển thị chỉ tên thuộc tính được định dạng như sau:

[`attributename`][module.ClassName.attributename]

Các phương thức nên được hiển thị kèm theo () sau không gian tên, do đó cần được xử lý khác với các thuộc tính. Dưới đây là cách thích hợp để liên kết đến một phương thức:

[`module.ClassName.methodname()`][module.ClassName.methodname]

Phần sau đây chỉ hiển thị tên lớp và tên phương thức. Điều này cũng yêu cầu phải thêm dấu ngoặc đơn sau tên:

[`Classname.methodname()`][module.Classname.methodname]

Bạn có thể tạo liên kết đến một lớp, phương thức hoặc thuộc tính đồng thời hiển thị văn bản tùy ý, bằng cách sử dụng phương thức tương tự với không gian tên phù hợp. Khi thực hiện điều này với một lớp, cú pháp sẽ như sau:

[văn bản liên kết][module.ClassName]

Bạn cũng có thể tạo liên kết trực tiếp đến tài liệu chính thức của Python cũng như tài liệu của Pillow. Ví dụ, để tạo liên kết đến tài liệu về int:

[`int`][]

Để truy cập tài liệu hướng dẫn về Pillow Image:

[`PIL.Image.Image`][]

Mẹo về khối mã

Tô màu cú pháp và ngôn ngữ

Bạn có thể chỉ định ngôn ngữ cho đoạn mã nằm trong khối mã bằng cách thêm tên ngôn ngữ ngay sau ba dấu gạch chéo ngược đầu tiên, không có khoảng trắng ở giữa. Điều này sẽ giúp đoạn mã được tô sáng đúng cách khi hiển thị. Ví dụ: để chỉ định ngôn ngữ Python, bạn cần bắt đầu khối mã bằng ```python.

Các lệnh trên bảng điều khiển và nút sao chép

Nếu bạn chèn các lệnh trên giao diện dòng lệnh hoặc các lệnh có kết quả hiển thị, hãy đánh dấu chúng bằng console hoặc doscon, tùy thuộc vào việc bạn đang mô tả hệ điều hành kiểu Unix (bao gồm macOS) hay Windows. Bạn có thể giữ nguyên dấu nhắc lệnh do hệ điều hành cung cấp; khi nhấp vào nút sao chép, chỉ lệnh đó sẽ được sao chép. Ví dụ: nếu bạn bắt đầu một khối mã bằng ```console và chèn nội dung sau:

$ mkdir test
$ ls
test

Khi đó, việc nhấp vào nút sao chép trên khối mã sẽ chỉ sao chép các lệnh, đồng thời bỏ qua các lời nhắc và kết quả đầu ra. Điều này giúp bạn chỉ ra rằng đó là các lệnh trên giao diện dòng lệnh, đồng thời vẫn cho phép người dùng sử dụng nút sao chép một cách hiệu quả.

Đánh dấu các dòng mã cụ thể

Bạn có thể làm nổi bật các dòng mã cụ thể. Ví dụ: để làm nổi bật dòng 2, bạn cần thêm một khoảng trắng sau tên ngôn ngữ, tiếp theo là {hl_lines="2"}. Như vậy, khối mã của bạn sẽ bắt đầu bằng ```python {hl_lines="2"}. Kết quả là:

import toga
from toga.style.pack import COLUMN, ROW

Bạn có thể đánh dấu nhiều dòng khác nhau. Ví dụ: python {hl_lines="3 5 9"} sẽ đánh dấu các dòng 3, 5 và 9. Bạn cũng có thể đánh dấu một dãy dòng. Ví dụ: python {hl_lines="3-8"} sẽ đánh dấu các dòng từ 3 đến 8. Bạn có thể đánh dấu nhiều dãy dòng, ví dụ như python {hl_lines="9-18 23-44"}.

Các thành phần Markdown yêu cầu định dạng cụ thể

Do cách thức tạo các tệp dịch, việc thêm các dòng mới bắt buộc vào cú pháp Markdown cho các phần cảnh báo, ghi chú, tab, lệnh Jinja, chú thích hình ảnh và căn chỉnh, v.v. là rất quan trọng.

Lời khuyên và lưu ý

Các lưu ý phải được định dạng như sau, bao gồm việc đảm bảo có một dòng mới trước và sau phần mở đầu và kết thúc của lưu ý:

Nội dung ở trên.

/// Lời khuyên | Tiêu đề

Nội dung lời khuyên.

Đoạn thứ hai.

///

Nội dung ở dưới.

Cách thức này cũng áp dụng tương tự cho bất kỳ loại cảnh báo nào được hỗ trợ. Ví dụ, các cảnh báo dạng ghi chú cũng yêu cầu định dạng và các dòng mới tương tự:

Nội dung ở trên.

/// ghi chú | Tiêu đề ghi chú

Nội dung ghi chú ở đây.

///

Nội dung ở dưới.

Tất cả các loại lời nhắc được hỗ trợ đều có thể được sử dụng làm lời nhắc.

Nội dung theo tab

Nội dung có tab được định dạng như sau, bao gồm một dòng mới được chèn vào trước phần đầu và sau phần cuối của khối nội dung:

Nội dung ở trên.

/// tab | Tiêu đề tab một

Nội dung tab một

///

/// tab | Tiêu đề tab hai

Nội dung tab hai.

///

/// tab | Tiêu đề tab ba

Nội dung tab ba.

///

Nội dung ở dưới.

Một tab có lời cảnh báo lồng nhau sẽ được định dạng như sau, bao gồm một dòng mới trước và sau khối nội dung:

Nội dung phía trên.

/// tab | Windows

Nội dung tab.

/// admonition | Lời nhắc nhở

Nội dung lời nhắc nhở.

///

///

Nội dung phía dưới.

Nội dung đã thu gọn

Nội dung được thu gọn được định dạng như sau, bao gồm cả các dòng mới:

Nội dung ở trên.

/// details-note | Tiêu đề nội dung đã thu gọn

Nội dung đã thu gọn.

///

Nội dung ở dưới.

Tất cả các loại cảnh báo được hỗ trợ đều có thể sử dụng với nội dung thu gọn, tuy nhiên, bạn phải khai báo chúng dưới dạng details-admonitiontype. Vì vậy, một khối thu gọn loại "note" sẽ là details-note (như đã trình bày ở trên), một khối thu gọn loại "warning" sẽ là details-warning, v.v.

Hướng dẫn về Jinja

Có một số phần trong tài liệu sử dụng các lệnh Jinja trong nội dung văn bản. Bất kỳ phần nào sử dụng các tính năng của lệnh Jinja đều phải được bao quanh bởi các ký tự xuống dòng. Ví dụ, hướng dẫn BeeWare chứa các điều kiện Jinja dựa trên biến để xác định lời nhắc nhở nào sẽ hiển thị trên trang chính. Chúng được định dạng như sau:

Nội dung phía trên.



Nội dung phía dưới.

Ngoài ra còn có cú pháp để thay thế các ký hiệu hoặc văn bản. Cú pháp này là một biến được bao quanh bởi một cặp dấu ngoặc nhọn kép, và nếu nằm trên một dòng riêng biệt, thì phải có ký tự xuống dòng trước và sau nó.

Nội dung ở trên.

{{ variable }}

Nội dung ở dưới.

Định dạng hình ảnh

Có thể thiết lập chiều rộng cho hình ảnh và căn chỉnh sang trái, phải hoặc giữa (với một lưu ý về tùy chọn "giữa"). Hình ảnh nên luôn đi kèm với văn bản thay thế (alt text) có ý nghĩa để đảm bảo tính khả dụng.

Việc đặt chiều rộng của hình ảnh là 300px sẽ được định dạng như sau:

![Chú thích hình ảnh](../path/to/image.png){ width="300px" }

Để căn lề trái (hoặc phải) cho một hình ảnh, bạn cần định dạng như sau:

![Chú thích hình ảnh](../path/to/image.png){ align=left }

Để thêm chú thích cho hình ảnh, cần có một dòng mới ở trước và sau chú thích, và chú thích được định dạng như sau:

Nội dung ở trên.

![Chú thích hình ảnh](../path/to/image.png)

/// chú thích

Nội dung chú thích.

///

Nội dung ở dưới.

Không thể căn giữa hình ảnh bằng thuộc tính align. Cách khắc phục là thêm một chú thích trống ngay sau hình ảnh, và hình ảnh sẽ được căn giữa. Bạn phải chèn các dòng mới giữa mỗi phần, cũng như trước và sau đó. Cách định dạng như sau:

Nội dung ở trên.

![Chú thích hình ảnh](../path/to/image.png)

/// chú thích

///

Nội dung ở dưới.

Các plugin hỗ trợ định dạng Markdown cụ thể

Các phần sau đây sẽ hướng dẫn cách sử dụng các plugin yêu cầu định dạng Markdown cụ thể.

Sử dụng Snippets để chèn nội dung bên ngoài

Để biết chi tiết về cách chèn nội dung bên ngoài từ tệp cục bộ hoặc URL, hãy tham khảo tài liệu hướng dẫn về tiện ích mở rộng Snippets. Nên sử dụng Snippets miễn là tài liệu không chứa các lệnh Jinja cần được thực thi (việc thực thi Jinja diễn ra song song với quá trình xử lý Snippets, do đó bất kỳ lệnh Jinja nào trong tệp sẽ không được xử lý). Snippets là cần thiết nếu bạn muốn sử dụng các dấu phân cách cho phép bạn chèn các phần cụ thể của tệp một cách riêng biệt, ví dụ: tài liệu nguồn được chia thành các phần để chèn riêng biệt với nhau.

Những lưu ý quan trọng:

  • Chúng tôi sử dụng -8<- làm mã định danh cho các đoạn mã mẫu. Tài liệu hướng dẫn nêu ra một số tùy chọn; vui lòng tuân thủ phong cách của chúng tôi.
  • Các tệp được tìm thấy trong nội dung chia sẻ của BeeWare Docs Tools được coi là nội dung "cục bộ". Do đó, bạn chỉ cần sử dụng tên tệp, như trong -8<- "docs-style-guide.md", hoặc nếu nội dung nằm trong một thư mục con, chỉ cần sử dụng tên thư mục và tên tệp, như trong -8<- "style/docs-style-guide.md".
  • Nếu bạn đang nhúng nội dung bên ngoài từ một tệp trên GitHub thông qua một URL, bạn phải sử dụng URL nội dung thô, nếu không trang web đầy đủ sẽ được hiển thị dưới dạng nhúng tại bất kỳ vị trí nào bạn chèn nó.

Sử dụng Macro để chèn nội dung từ nội dung được chia sẻ của BeeWare Docs Tools

Bạn cũng có thể chèn nội dung từ thư mục nội dung chia sẻ của các công cụ BeeWare Docs bằng cách sử dụng tiện ích mở rộng Macros MkDocs. Phương pháp này là cần thiết nếu tài liệu chứa các chỉ thị Jinja cần được thực thi, và chỉ nên được sử dụng trong trường hợp này. Phương pháp này sẽ không hoạt động với nội dung bên ngoài thông qua URL. Cơ chế thay thế biến của Macros hoạt động với phương pháp này.

Có các tùy chọn để chèn nội dung bằng cách sử dụng Macro:

  1. Hãy sử dụng cú pháp include Jinja nếu bạn muốn nhúng tài liệu mà không cần thực hiện bất kỳ thay đổi thủ công nào khác.

  2. Hãy sử dụng cú pháp Jinja extends nếu bạn đã chèn cú pháp Jinja block vào tài liệu, điều này cho phép bạn ghi đè hoặc bổ sung nội dung vào các phần cụ thể.

pyspelling

Chúng tôi sử dụng trình kiểm tra chính tả pyspelling. Trình này được chạy trong quá trình kiểm tra lint.

Khi pyspelling phát hiện một từ bị viết sai chính tả, trong hầu hết các trường hợp, từ đó cần được sửa lại trong nội dung tài liệu.

Trong trường hợp hiếm hoi khi chương trình phát hiện ra một từ hợp lệ nhưng không có trong từ điển pyspelling, bạn có hai lựa chọn:

  1. Nếu đó là một từ có khả năng được sử dụng lại nhiều lần, bạn nên thêm từ đó vào tệp spelling_wordlist trong thư mục docs, theo thứ tự bảng chữ cái.
  2. Nếu đó là một từ ít có khả năng được sử dụng lại, bạn có thể đặt nó trong thẻ <nospell> / </nospell>, và pyspelling sẽ bỏ qua nó trong dòng.