Đóng góp vào tài liệu TensorFlow

TensorFlow hoan nghênh những đóng góp về tài liệu—nếu bạn cải thiện tài liệu, bạn sẽ cải thiện chính thư viện TensorFlow. Tài liệu trên tensorflow.org thuộc các loại sau:

Một số dự án TensorFlow giữ các tệp nguồn tài liệu gần mã trong một kho lưu trữ riêng, thường là trong thư mục docs/ . Xem tệp CONTRIBUTING.md của dự án hoặc liên hệ với người bảo trì để đóng góp.

Để tham gia cộng đồng tài liệu TensorFlow:

Tham chiếu API

Để biết chi tiết, hãy sử dụng hướng dẫn cộng tác viên tài liệu API TensorFlow . Phần này hướng dẫn bạn cách tìm tệp nguồn và chỉnh sửa chuỗi tài liệu của ký hiệu. Nhiều trang tham chiếu API trên tensorflow.org bao gồm liên kết đến tệp nguồn nơi ký hiệu được xác định. Chuỗi tài liệu hỗ trợ Markdown và có thể được xem trước (xấp xỉ) bằng bất kỳ trình xem trước Markdown nào.

Phiên bản và nhánh

Phiên bản tham chiếu API của trang web được mặc định là phiên bản nhị phân ổn định mới nhất—phiên bản này khớp với gói được cài đặt với pip install tensorflow .

Gói TensorFlow mặc định được xây dựng từ nhánh ổn định rX.x trong repo tensorflow/tensorflow chính. Tài liệu tham khảo được tạo từ các nhận xét mã và chuỗi tài liệu trong mã nguồn của Python , C++ và Java .

Các phiên bản trước của tài liệu TensorFlow có sẵn dưới dạng các nhánh rX.x trong kho Tài liệu TensorFlow. Các nhánh này được thêm vào khi một phiên bản mới được phát hành.

Xây dựng tài liệu API

Tham chiếu Python

Gói tensorflow_docs bao gồm trình tạo tài liệu tham khảo API Python . Để cài đặt:

pip install git+https://github.com/tensorflow/docs

Để tạo tài liệu tham khảo TensorFlow 2, hãy sử dụng tập tensorflow/tools/docs/generate2.py :

git clone https://github.com/tensorflow/tensorflow tensorflow
cd tensorflow/tensorflow/tools/docs
pip install tensorflow
python generate2.py --output_dir=/tmp/out

Tài liệu tường thuật

Các hướng dẫn và hướng dẫn về TensorFlow được viết dưới dạng tệp Markdown và sổ ghi chép Jupyter tương tác. Sổ ghi chép có thể chạy trong trình duyệt của bạn bằng Google Colaboratory . Các tài liệu tường thuật trên tensorflow.org được xây dựng từ nhánh master tensorflow/docs . Các phiên bản cũ hơn có sẵn trong GitHub trên nhánh phát hành rX.x

Những thay đổi đơn giản

Cách dễ nhất để thực hiện cập nhật tài liệu đơn giản cho các tệp Markdown là sử dụng trình chỉnh sửa tệp dựa trên web của GitHub. Duyệt qua kho lưu trữ tensorflow/docs để tìm Markdown gần tương ứng với cấu trúc URL tensorflow.org . Ở góc trên bên phải của chế độ xem tệp, hãy nhấp vào biểu tượng bút chì để mở trình soạn thảo tập tin. Chỉnh sửa tệp và sau đó gửi yêu cầu kéo mới.

Thiết lập repo Git cục bộ

Đối với các chỉnh sửa nhiều tệp hoặc các bản cập nhật phức tạp hơn, tốt hơn nên sử dụng quy trình làm việc Git cục bộ để tạo yêu cầu kéo.

Các bước Git sau chỉ được yêu cầu khi bạn thiết lập dự án cục bộ lần đầu tiên.

Phân nhánh repo tensorflow/docs

Trên trang GitHub tensorflow/docs , nhấp vào nút Fork để tạo bản sao repo của riêng bạn trong tài khoản GitHub của bạn. Sau khi phân nhánh, bạn có trách nhiệm cập nhật bản sao kho lưu trữ của mình với kho lưu trữ TensorFlow ngược dòng.

Sao chép kho lưu trữ của bạn

Tải xuống bản username /tài liệu từ xa về máy cục bộ của bạn . Đây là thư mục làm việc nơi bạn sẽ thực hiện các thay đổi: 

git clone git@github.com:username/docs
cd ./docs

Thêm kho lưu trữ ngược dòng để cập nhật (tùy chọn)

Để giữ cho kho lưu trữ cục bộ của bạn được đồng bộ hóa với tensorflow/docs , hãy thêm một điều khiển từ xa ngược dòng để tải xuống những thay đổi mới nhất.

Thêm một điều khiển từ xa:

git remote add upstream git@github.com:tensorflow/docs.git

# View remote repos
git remote -v
origin    git@github.com:username/docs.git (fetch)
origin    git@github.com:username/docs.git (push)
upstream  git@github.com:tensorflow/docs.git (fetch)
upstream  git@github.com:tensorflow/docs.git (push)

Để cập nhật: 

git checkout master
git pull upstream master

git push  # Push changes to your GitHub account (defaults to origin)

Quy trình làm việc của GitHub

1. Tạo một nhánh mới

Sau khi bạn cập nhật repo của mình từ tensorflow/docs , hãy tạo một nhánh mới từ nhánh chính cục bộ: 

git checkout -b feature-name

git branch  # List local branches
  master

* feature-name

2. Thực hiện thay đổi

Chỉnh sửa tệp trong trình chỉnh sửa yêu thích của bạn và vui lòng làm theo hướng dẫn về kiểu tài liệu TensorFlow .

Cam kết thay đổi tập tin của bạn:

# View changes
git status  # See which files have changed
git diff    # See changes within files

git add path/to/file.md
git commit -m "Your meaningful commit message for the change."

Thêm nhiều cam kết hơn, nếu cần thiết.

3. Tạo yêu cầu kéo

Tải chi nhánh địa phương của bạn lên kho lưu trữ GitHub từ xa ( username /docs):

git push

Sau khi quá trình đẩy hoàn tất, một thông báo có thể hiển thị một URL để tự động gửi yêu cầu kéo tới kho lưu trữ ngược dòng. Nếu không, hãy truy cập kho lưu trữ tensorflow/docs —hoặc kho lưu trữ của riêng bạn—và GitHub sẽ nhắc bạn tạo yêu cầu kéo.

4. Xem xét

Người bảo trì và những người đóng góp khác sẽ xem xét yêu cầu kéo của bạn. Hãy tham gia thảo luận và thực hiện những thay đổi được yêu cầu. Khi yêu cầu kéo của bạn được phê duyệt, nó sẽ được hợp nhất vào kho lưu trữ tài liệu TensorFlow ngược dòng.

Có một bước xuất bản riêng để cập nhật tensorflow.org từ kho lưu trữ GitHub. Thông thường, các thay đổi được gộp lại với nhau và trang web được cập nhật theo nhịp độ đều đặn.

Sổ tay tương tác

Mặc dù có thể chỉnh sửa tệp JSON của sổ tay bằng trình chỉnh sửa tệp dựa trên web của GitHub nhưng bạn không nên làm như vậy vì JSON không đúng định dạng có thể làm hỏng tệp. Đảm bảo kiểm tra sổ ghi chép trước khi gửi yêu cầu kéo.

Google Colaboratory là môi trường sổ ghi chép được lưu trữ giúp dễ dàng chỉnh sửa—và chạy—tài liệu sổ ghi chép. Sổ ghi chép trong GitHub được tải trong Google Colab bằng cách chuyển đường dẫn đến URL Colab, ví dụ: sổ ghi chép nằm trong GitHub tại đây: https://github.com/tensorflow/docs/blob/master/site/en/tutorials/keras /phân loại.ipynb
có thể được tải vào Google Colab tại URL này: https://colab.research.google.com/github/tensorflow/docs/blob/master/site/en/tutorials/keras/classification.ipynb

Có một tiện ích mở rộng Open in Colab của Chrome thực hiện việc thay thế URL này khi duyệt sổ ghi chép trên GitHub. Điều này rất hữu ích khi mở sổ ghi chép trong nhánh repo của bạn, vì các nút trên cùng luôn liên kết với nhánh master của TensorFlow Docs.

Định dạng sổ tay

Công cụ định dạng sổ ghi chép giúp cho nguồn sổ ghi chép Jupyter có sự khác biệt nhất quán và dễ xem xét hơn. Vì môi trường soạn thảo sổ ghi chép khác nhau về đầu ra tệp, thụt lề, siêu dữ liệu và các trường không được chỉ định khác; nbfmt sử dụng các giá trị mặc định có ý kiến ​​với ưu tiên dành cho quy trình làm việc Colab của tài liệu TensorFlow. Để định dạng sổ ghi chép, hãy cài đặt công cụ sổ ghi chép tài liệu TensorFlow và chạy công cụ nbfmt :

# Install the tensorflow-docs package:
$ python3 -m pip install -U [--user] git+https://github.com/tensorflow/docs

$ python3 -m tensorflow_docs.tools.nbfmt [options] notebook.ipynb [...]

Đối với các dự án tài liệu TensorFlow, sổ ghi chép không có ô đầu ra sẽ được thực thi và kiểm tra; sổ ghi chép có ô đầu ra đã lưu sẽ được xuất bản nguyên trạng. nbfmt tôn trọng trạng thái sổ ghi chép và sử dụng tùy chọn --remove_outputs để xóa rõ ràng các ô đầu ra.

Để tạo sổ ghi chép mới, hãy sao chép và chỉnh sửa mẫu sổ ghi chép tài liệu TensorFlow .

Chỉnh sửa trong Colab

Trong môi trường Google Colab, hãy nhấp đúp vào các ô để chỉnh sửa khối văn bản và mã. Các ô văn bản sử dụng Markdown và phải tuân theo hướng dẫn về kiểu tài liệu TensorFlow .

Tải xuống các tệp sổ tay từ Colab bằng Tệp > Tải xuống .pynb . Cam kết tệp này với kho lưu trữ Git cục bộ của bạn và gửi yêu cầu kéo.

Để tạo sổ ghi chép mới, hãy sao chép và chỉnh sửa mẫu sổ ghi chép TensorFlow .

Quy trình làm việc của Colab-GitHub

Thay vì tải xuống tệp sổ ghi chép và sử dụng quy trình làm việc Git cục bộ, bạn có thể chỉnh sửa và cập nhật kho lưu trữ GitHub được phân nhánh của mình trực tiếp từ Google Colab:

  1. Trong kho lưu trữ username /tài liệu được chia nhánh của bạn, hãy sử dụng giao diện người dùng web GitHub để tạo một nhánh mới .
  2. Điều hướng đến tệp sổ ghi chép để chỉnh sửa.
  3. Mở sổ ghi chép trong Google Colab: sử dụng tính năng hoán đổi URL hoặc tiện ích mở rộng Mở trong Colab của Chrome.
  4. Chỉnh sửa sổ ghi chép trong Colab.
  5. Cam kết các thay đổi đối với kho lưu trữ của bạn từ Colab bằng Tệp > Lưu bản sao trong GitHub... . Hộp thoại lưu sẽ liên kết đến repo và nhánh thích hợp. Thêm một thông điệp cam kết có ý nghĩa.
  6. Sau khi lưu, hãy duyệt đến kho lưu trữ của bạn hoặc kho lưu trữ tensorflow/docs , GitHub sẽ nhắc bạn tạo yêu cầu kéo.
  7. Yêu cầu kéo được xem xét bởi người bảo trì.

Bản dịch

Nhóm TensorFlow làm việc với cộng đồng và nhà cung cấp để cung cấp bản dịch cho tensorflow.org. Bản dịch của sổ ghi chép và nội dung kỹ thuật khác nằm trong kho lưu trữ tensorflow/docs-l10n GitHub. Vui lòng gửi yêu cầu kéo thông qua dự án TensorFlow GitLocalize .

Các tài liệu tiếng Anh là nguồn gốc của sự thật và các bản dịch nên tuân theo những hướng dẫn này càng sát càng tốt. Điều đó có nghĩa là các bản dịch được viết cho cộng đồng mà chúng phục vụ. Nếu thuật ngữ, cách diễn đạt, phong cách hoặc giọng điệu tiếng Anh không dịch sang ngôn ngữ khác, vui lòng sử dụng bản dịch phù hợp với người đọc.

Hỗ trợ ngôn ngữ được xác định bởi một số yếu tố bao gồm—nhưng không giới hạn—số liệu và nhu cầu của trang web, hỗ trợ cộng đồng, trình độ tiếng Anh , sở thích của khán giả và các chỉ số khác. Vì mỗi ngôn ngữ được hỗ trợ đều phát sinh chi phí nên các ngôn ngữ không được bảo trì sẽ bị xóa. Hỗ trợ cho các ngôn ngữ mới sẽ được công bố trên blog TensorFlow hoặc Twitter .

Nếu ngôn ngữ ưa thích của bạn không được hỗ trợ, bạn có thể duy trì một nhánh cộng đồng dành cho những người đóng góp nguồn mở. Chúng không được xuất bản lên tensorflow.org.