Hướng dẫn về phong cách tài liệu TensorFlow

Thực hành tốt nhất

Giảm giá

Với một vài ngoại lệ, TensorFlow sử dụng cú pháp Markdown tương tự như GitHub Flavored Markdown (GFM). Phần này giải thích sự khác biệt giữa cú pháp GFM Markdown và Markdown được sử dụng cho tài liệu TensorFlow.

Viết về mã

Đề cập nội tuyến của mã

Đặt `backticks` xung quanh các ký hiệu sau khi sử dụng trong văn bản:

  • Tên đối số: `input` , `x` , `tensor`
  • Tên tensor được trả về: `output` , `idx` , `out`
  • Các kiểu dữ liệu: `int32` , `float` , `uint8`
  • Tham chiếu tên op khác trong văn bản: `list_diff()` , `shuffle()`
  • Tên lớp: `tf.Tensor` , `Strategy`
  • Tên tệp: `image_ops.py` , `/path_to_dir/file_name`
  • Biểu thức hoặc điều kiện toán học: `-1-input.dims() <= dim <= input.dims()`

Khối mã

Sử dụng ba dấu backticks để mở và đóng một khối mã. Tùy chọn chỉ định ngôn ngữ lập trình sau nhóm backtick đầu tiên, ví dụ:


```python
# some python code here
```

Sử dụng các liên kết tương đối giữa các tệp trong một kho lưu trữ GitHub. Bao gồm phần mở rộng tập tin.

Ví dụ: tệp bạn đang đọc này được lấy từ kho lưu trữ https://github.com/tensorflow/docs . Do đó, nó có thể sử dụng các đường dẫn tương đối để liên kết đến các file khác trong cùng kho lưu trữ như thế này:

  • [Basics](../../guide/basics.ipynb) tạo ra Basics .

Đây là phương pháp được ưa thích vì theo cách này, các liên kết trên tensorflow.org , GitHub và Colab đều hoạt động. Ngoài ra, người đọc vẫn ở lại trang đó khi họ nhấp vào một liên kết.

Đối với các liên kết đến các tệp không có trong kho lưu trữ hiện tại, hãy sử dụng các liên kết Markdown tiêu chuẩn có URI đầy đủ. Ưu tiên liên kết tới URI tensorflow.org nếu nó có sẵn.

Để liên kết đến mã nguồn, hãy sử dụng liên kết bắt đầu bằng https://www.github.com/tensorflow/tensorflow/blob/master/ , theo sau là tên tệp bắt đầu từ thư mục gốc GitHub.

Khi liên kết với tenorflow.org , hãy bao gồm {:.external} trên liên kết Markdown để biểu tượng "liên kết ngoài" được hiển thị.

  • [GitHub](https://github.com/tensorflow/docs){:.external} sản xuất GitHub

Không bao gồm các tham số truy vấn URI trong liên kết:

  • Sử dụng: <a href="https://www.tensorflow.org/guide/data">https://www.tensorflow.org/guide/data</a>
  • Không phải: <a href="https://www.tensorflow.org/guide/data?hl=en">https://www.tensorflow.org/guide/data?hl=en</a>

Hình ảnh

Lời khuyên trong phần trước là dành cho các liên kết đến các trang. Hình ảnh được xử lý khác nhau.

Nói chung, bạn không nên kiểm tra hình ảnh mà thay vào đó hãy thêm nhóm TensorFlow-Docs vào PR của bạn và yêu cầu họ lưu trữ hình ảnh trên tensorflow.org . Điều này giúp giảm kích thước kho lưu trữ của bạn.

Nếu bạn gửi hình ảnh đến kho lưu trữ của mình, hãy lưu ý rằng một số hệ thống không xử lý đường dẫn tương đối đến hình ảnh. Ưu tiên sử dụng URL đầy đủ trỏ đến vị trí cuối cùng của hình ảnh trên tensorflow.org .

Liên kết API được chuyển đổi khi trang web được xuất bản. Để liên kết đến trang tham chiếu API của biểu tượng, hãy đặt đường dẫn biểu tượng trong dấu gạch chéo ngược:

Đường dẫn đầy đủ được ưa thích hơn một chút ngoại trừ đường dẫn dài. Đường dẫn có thể được viết tắt bằng cách loại bỏ các thành phần đường dẫn dẫn đầu. Đường dẫn một phần sẽ được chuyển đổi thành liên kết nếu:

  • Có ít nhất một . trên đường đi và
  • Đường dẫn một phần là duy nhất trong dự án.

Đường dẫn API được liên kết cho mọi dự án bằng API Python được xuất bản trên tensorflow.org . Bạn có thể dễ dàng liên kết đến nhiều dự án con từ một tệp duy nhất bằng cách gói tên API bằng dấu backticks. Ví dụ:

Đối với các biểu tượng có nhiều bí danh đường dẫn, có một ưu tiên nhỏ cho đường dẫn khớp với trang API trên tensorflow.org . Tất cả các bí danh sẽ chuyển hướng đến đúng trang.

Toán trong Markdown

Bạn có thể sử dụng MathJax trong TensorFlow khi chỉnh sửa tệp Markdown, nhưng hãy lưu ý những điều sau:

  • MathJax hiển thị chính xác trên tensorflow.org .
  • MathJax không hiển thị chính xác trên GitHub.
  • Ký hiệu này có thể gây khó chịu cho các nhà phát triển không quen.
  • Để có tính nhất quán, tensorflow.org tuân theo các quy tắc tương tự như Jupyter/Colab.

Sử dụng $$ xung quanh một khối MathJax:

$$
E=\frac{1}{2n}\sum_x\lVert (y(x)-y'(x)) \rVert^2
$$

\[ E=\frac{1}{2n}\sum_x\lVert (y(x)-y'(x)) \rVert^2 \]

Gói các biểu thức MathJax nội tuyến bằng $ ... $ :


This is an example of an inline MathJax expression: $ 2 \times 2 = 4 $

Đây là ví dụ về biểu thức MathJax nội tuyến: \( 2 \times 2 = 4 \)

Dấu phân cách \\( ... \\) cũng có tác dụng đối với phép toán nội tuyến, nhưng dạng $ đôi khi dễ đọc hơn.

Phong cách văn xuôi

Nếu bạn định viết hoặc chỉnh sửa các phần quan trọng của tài liệu tường thuật, vui lòng đọc Hướng dẫn về Phong cách Tài liệu dành cho Nhà phát triển của Google .

Nguyên tắc của phong cách tốt

  • Kiểm tra chính tả và ngữ pháp trong đóng góp của bạn. Hầu hết các trình soạn thảo đều có trình kiểm tra chính tả hoặc có sẵn plugin kiểm tra chính tả. Bạn cũng có thể dán văn bản của mình vào Google Doc hoặc phần mềm tài liệu khác để kiểm tra chính tả và ngữ pháp hiệu quả hơn.
  • Sử dụng giọng nói giản dị và thân thiện. Viết tài liệu TensorFlow giống như một cuộc trò chuyện—như thể bạn đang nói chuyện trực tiếp với người khác. Sử dụng giọng điệu hỗ trợ trong bài viết.
  • Tránh tuyên bố từ chối trách nhiệm, ý kiến ​​và đánh giá giá trị. Những từ như "dễ dàng", "chỉ" và "đơn giản" chứa đầy những giả định. Một điều gì đó có thể dễ dàng với bạn nhưng lại khó khăn với người khác. Cố gắng tránh những điều này bất cứ khi nào có thể.
  • Sử dụng các câu đơn giản, chính xác, không dùng biệt ngữ phức tạp. Các câu ghép, chuỗi mệnh đề và thành ngữ theo vị trí cụ thể có thể khiến văn bản khó hiểu và khó dịch. Nếu một câu có thể chia làm hai thì có lẽ nên làm như vậy. Tránh dấu chấm phẩy. Sử dụng danh sách dấu đầu dòng khi thích hợp.
  • Cung cấp bối cảnh. Đừng sử dụng chữ viết tắt mà không giải thích chúng. Đừng đề cập đến các dự án không phải của TensorFlow mà không liên kết với chúng. Giải thích tại sao mã được viết như vậy.

Hướng dẫn sử dụng

Rất tiếc

Trong các tệp đánh dấu, hãy sử dụng # ⇒ thay vì một dấu bằng khi bạn muốn hiển thị kết quả trả về của một op.

# 'input' is a tensor of shape [2, 3, 5]
tf.expand_dims(input, 0)  # ⇒ [1, 2, 3, 5]

Trong sổ ghi chép, hiển thị kết quả thay vì thêm nhận xét (Nếu biểu thức cuối cùng trong ô sổ ghi chép không được gán cho một biến, nó sẽ tự động được hiển thị.)

Trong tài liệu tham khảo API thích sử dụng doctest để hiển thị kết quả.

Tenxơ

Khi bạn nói về tensor nói chung, đừng viết hoa từ tensor . Khi bạn đang nói về đối tượng cụ thể được cung cấp hoặc trả về từ một op, thì bạn nên viết hoa từ Tensor và thêm dấu tích ngược xung quanh nó vì bạn đang nói về đối tượng Tensor .

Đừng sử dụng từ Tensors (số nhiều) để mô tả nhiều đối tượng Tensor trừ khi bạn thực sự đang nói về một đối tượng Tensors . Thay vào đó, hãy nói "danh sách (hoặc bộ sưu tập) các đối tượng Tensor ".

Sử dụng hình dạng từ để mô tả chi tiết các trục của một tenxơ và hiển thị hình dạng đó trong dấu ngoặc vuông có dấu ngược lại. Ví dụ:


If `input` is a three-axis `Tensor` with shape `[3, 4, 3]`, this operation
returns a three-axis `Tensor` with shape `[6, 8, 6]`.

Như trên, hãy ưu tiên "trục" hoặc "chỉ mục" hơn "thứ nguyên" khi nói về các phần tử của hình dạng của Tensor . Nếu không thì rất dễ nhầm lẫn "chiều" với chiều của không gian vectơ. Một "vectơ ba chiều" có một trục có chiều dài bằng 3.