Attend the Women in ML Symposium on December 7 Register now

Hướng dẫn kiểu tài liệu TensorFlow

Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.

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

  • Tập trung vào mục đích của người dùng và đối tượng.
  • Sử dụng các từ hàng ngày và giữ các câu ngắn gọn.
  • Sử dụng cấu trúc câu, từ ngữ và cách viết hoa nhất quán.
  • Sử dụng các tiêu đề và danh sách để quét tài liệu của bạn dễ dàng hơn.
  • Hướng dẫn về kiểu tài liệu dành cho nhà phát triển của Google rất hữu ích.

Markdown

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 về mã

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

  • Tên đối số: `input` , `x` x`, `tensor`
  • Tên tensor trả về: `output` , `idx` , `out`
  • 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`
  • Các 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 gạch ngược để mở và đóng một khối mã. Theo 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 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.

Ví dụ: tệp bạn đang đọc này là 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 tệp khác trong cùng một kho lưu trữ như sau:

Đây là cách tiếp cận được ưa chuộng vì theo cách này, các liên kết trên tensorflow.org , GitHubColab đều hoạt động. Ngoài ra, người đọc vẫn ở trong cùng một trang web 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 với URI đầy đủ. Thích liên kết đến 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ừ GitHub root.

Khi tắt liên kết của tensorflow.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 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 đăng ký hình ảnh, 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 vào kho lưu trữ của mình, hãy lưu ý rằng một số hệ thống không xử lý các đường dẫn tương đối đến hình ảnh. Thích sử dụng URL đầy đủ trỏ đến vị trí cuối cùng của hình ảnh trên tensorflow.org .

Các 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 ngược:

Các đường dẫn đầy đủ được ưu tiên hơn một chút ngoại trừ các đường dẫn dài. Đường dẫn có thể được viết tắt bằng cách bỏ các thành phần đường dẫn đầu. Các đườ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 . trong đường dẫn, và
  • Đường dẫn một phần là duy nhất trong dự án.

Các đường dẫn API được liên kết cho mọi dự án với 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 bọc các tên API bằng dấu gạch ngược. Ví dụ:

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

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ị đúng 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 thuộc.
  • Để 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 \]

Kết hợp các biểu thức MathJax nội dòng với $ ... $ :


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

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

Dấu phân cách \\( ... \\) cũng hoạt động đối với toán học nội tuyến, nhưng biểu mẫu $ đô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 kiểu 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 các đóng góp của bạn. Hầu hết các trình chỉnh sửa đều bao gồm trình kiểm tra chính tả hoặc có sẵn một 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 mạnh mẽ hơn.
  • Sử dụng một giọng nói bình thường 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 một giọng điệu ủng hộ trong bài báo.
  • Tránh các tuyên bố từ chối trách nhiệm, ý kiến ​​và đánh giá giá trị. Các từ như "dễ dàng", "đơn giản" và "đơn giản" chứa đầy các giả định. Điều gì đó có vẻ 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, trọng tâm mà không có 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ể được chia thành hai, nó có lẽ nên. 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 ngữ cảnh. Đừng sử dụng các từ 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 TensorFlow mà không liên kết với chúng. Giải thích tại sao mã được viết theo cách của nó.

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

Hoạt động

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

# '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 tài liệu để hiển thị kết quả.

Căng thẳng

Khi bạn đang nói về một 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ả lại từ một op, thì bạn nên viết hoa từ Tensor và thêm dấu gạch ngược xung quanh nó vì bạn đang nói về đối tượng Tensor .

Khô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 tensor và hiển thị hình dạng trong dấu ngoặc vuông có dấu ngoặc vuông. 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, ưu tiên "trục" hoặc "chỉ số" hơn "kích thước" khi nói về các phần tử của hình dạng Tensor . Nếu không, rất dễ nhầm lẫn "thứ nguyên" với thứ nguyên của không gian vectơ. Một "vectơ ba chiều" có một trục với độ dài 3.