Đó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

Để 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 . Điều này chỉ cho bạn cách tìm tệp nguồn và chỉnh sửa chuỗi tài liệu của biểu tượng . 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.

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 ++ 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 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

Hướng dẫn và hướng dẫn của TensorFlow được viết dưới dạng tệp Markdown và sổ ghi chép Jupyter tương tác. 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ừ nhánh chính của master / docs . 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ậ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 fork, 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 xuống bản sao của repo username / tài liệu từ xa của bạn vào 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 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 một đ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)

Quy trình làm việc GitHub

1. Tạo một chi 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 các 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ộ lên repo GitHub từ xa của bạn (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 truy cập vào kho tensorflow / docs — hoặc repo của riêng bạn — và GitHub sẽ nhắc bạn tạo một yêu cầu kéo.

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. Hãy tham gia vào cuộc 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.

Máy tính xách 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 bạn 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 rất hữu ích khi mở một 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ổ tay làm cho nguồn sổ tay 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 của TensorFlow docs Colab. Để đị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 như 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 các ô đầu ra một cách rõ ràng.

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

Tải xuống 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 một yêu cầu kéo.

Để tạo một 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 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 đã 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ị loại bỏ. 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 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.