Google is committed to advancing racial equity for Black communities. See how.
Trang này được dịch bởi Cloud Translation API.
Switch to English

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

TensorFlow hoan nghênh các đó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 biệt, thường là trong một 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 vào cộng đồng tài liệu TensorFlow:

Tham chiếu API

Để tham khảo tài liệu hướng dẫn cập nhật, tìm ra file nguồn và chỉnh sửa của biểu tượng docstring . Nhiều trang tham chiếu API trên tensorflow.org bao gồm một liên kết đến tệp nguồn nơi ký hiệu được xác định. Docstrings hỗ trợ Markdown và có thể được xem trước (gần đúng) bằng bất kỳ trình xem trước Markdown nào.

Để biết chất lượng tài liệu tham khảo và cách tham gia với các sprint doc và cộng đồng, hãy xem lời khuyên về Tài liệu API của TensorFlow 2 .

Các phiên bản và chi nhánh

Phiên bản tham chiếu API của trang web được đặt mặc định là tệp nhị phân ổn định mới nhất — điều này khớp với gói được cài đặt bằng 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 chú thích mã và chuỗi doc trong mã nguồn cho Python , C ++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 lưu trữ Tài liệu TensorFlow. Các nhánh này được thêm vào khi phiên bản mới được phát hành.

Tạo tài liệu API

Tham khảo Python

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

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

Để tạo tài liệu tham chiếu 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

TensorFlow hướng dẫnhướng dẫn được viết như Markdown tập tin và tương tác Jupyter máy tính xách tay. Sổ tay có thể được 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ừ các tensorflow / docs master chi nhánh. Các phiên bản cũ hơn có sẵn trong GitHub trên các nhánh phát hành rX.x

Thay đổi đơn giản

Cách dễ nhất để cập nhật tài liệu đơn giản cho 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, nhấp vào biểu tượng bút chì để mở trình chỉnh sửa tệp. Chỉnh sửa tệp và sau đó gửi một 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 đây chỉ được yêu cầu trong lần đầu tiên bạn thiết lập một dự án cục bộ.

Fork tensorflow / docs repo

Trên trang tensorflow / docs GitHub, 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 được phân nhánh, bạn có trách nhiệm cập nhật bản sao repo của mình với repo TensorFlow ngược dòng.

Sao chép repo của bạn

Tải bản sao từ xa của bạn username / docs repo để máy tính 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 repo ngược dòng để luôn cập nhật (tùy chọn)

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

Thêm đ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)

Dòng công việc GitHub

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

Sau khi cập nhật repo của bạn từ tensorflow/docs , tạo ra một chi nhánh mới từ chi nhánh tổng thể địa phương:

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 kiểu tài liệu TensorFlow .

Cam kết thay đổi tệp 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, nếu cần.

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

Tải chi nhánh cục bộ của bạn lên repo GitHub từ xa (github.com/ 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ị URL để tự động gửi yêu cầu kéo đến repo ngược dòng. Nếu không, hãy chuyển đến tensorflow / docs repo — hoặc repo của riêng bạn — và GitHub sẽ nhắc bạn tạo một pull request.

4. Đánh giá

Những 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. Vui lòng tham gia thảo luận và thực hiện các thay đổi được yêu cầu. Khi yêu cầu kéo của bạn được chấp thuận, nó sẽ được hợp nhất vào repo 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 GitHub. Thông thường, các thay đổi được thực hiện cùng nhau và trang web được cập nhật theo nhịp thường xuyên.

Sổ tay tương tác

Mặc dù có thể chỉnh sửa tệp JSON sổ ghi chép bằng trình chỉnh sửa tệp dựa trên web của GitHub, nhưng điều này không được khuyến khích 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ột 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ổ tay. Sổ tay trong GitHub được tải trong Google Colab bằng cách chuyển đường dẫn đến URL Colab, ví dụ: sổ tay nằm trong GitHub tại đây: https://github.com/tensorflow/docs/blob/master/site/en/tutorials/keras /classification.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 Mở trong Colab Chrome thực hiện thay thế URL này khi duyệt sổ ghi chép trên GitHub. Điều này hữu ích khi mở sổ ghi chép trong repo fork của bạn, vì các nút trên cùng luôn liên kết đến nhánh master của TensorFlow Docs.

Định dạng sổ tay

Một công cụ định dạng sổ ghi chép làm cho nguồn sổ ghi chép Jupyter khác biệt và dễ xem lại hơn. Vì môi trường tạo sổ ghi chép khác nhau liên quan đến đầ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 xác định với tùy chọn 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 được thực thi và kiểm tra; sổ ghi chép với các ô đầu ra đã lưu đượ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 để loại bỏ rõ ràng các ô đầu ra.

Để tạo sổ tay mới, hãy sao chép và chỉnh sửa mẫu sổ tay 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 văn bản và khối mã. Các ô văn bản sử dụng Markdown và phải tuân theo hướng dẫn kiểu tài liệu TensorFlow .

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

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

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

Thay vì tải xuống tệp sổ tay 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 repo GitHub đã phân nhánh của mình trực tiếp từ Google Colab:

  1. Trong repo username / tài liệu được phân 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ổ tay trong Google Colab: sử dụng hoán đổi URL hoặc tiện ích mở rộng Mở trong Colab Chrome.
  4. Chỉnh sửa sổ ghi chép trong Colab.
  5. Cam kết các thay đổi đối với kho của bạn từ Colab bằng Tệp> Lưu bản sao trong GitHub .... Hộp thoại lưu phải 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, duyệt đến repo của bạn hoặc repo tensorflow / docs , GitHub sẽ nhắc bạn tạo một yêu cầu kéo.
  7. Yêu cầu kéo được xem xét bởi các nhà bảo trì.

Bản dịch

Nhóm TensorFlow làm việc với cộng đồng và các nhà cung cấp để cung cấp các bản dịch cho tensorflow.org. Bản dịch sổ tay 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 các 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 chân lý và các bản dịch phải tuân theo các hướng dẫn này càng sát càng tốt. Điều đó nói rằng, các bản dịch được viết cho các cộng đồng mà họ phục vụ. Nếu thuật ngữ tiếng Anh, cách diễn đạt, văn phong hoặc giọng điệu 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 — chỉ số 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ợ phải chịu một khoản phí, các ngôn ngữ không rõ ràng sẽ bị xóa. Hỗ trợ cho các ngôn ngữ mới sẽ được thông báo trên blog hoặc Twitter của TensorFlow .

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 cho những người đóng góp nguồn mở. Chúng không được xuất bản lên tensorflow.org.