Thanks for tuning in to Google I/O. View all sessions on demandWatch on demand

Przyczyń się do tworzenia dokumentacji TensorFlow

TensorFlow z zadowoleniem przyjmuje wkład w dokumentację — jeśli ulepszysz dokumentację, ulepszysz samą bibliotekę TensorFlow. Dokumentacja na tensorflow.org dzieli się na następujące kategorie:

Niektóre projekty TensorFlow przechowują pliki źródłowe dokumentacji w pobliżu kodu w osobnym repozytorium, zwykle w katalogu docs/ . Zobacz plik CONTRIBUTING.md projektu lub skontaktuj się z opiekunem, aby wnieść swój wkład.

Aby wziąć udział w społeczności dokumentów TensorFlow:

Dokumentacja API

Aby uzyskać szczegółowe informacje, skorzystaj z przewodnika dla autorów dokumentacji TensorFlow API . To pokazuje, jak znaleźć plik źródłowy i edytować docstring symbolu. Wiele stron referencyjnych API na tensorflow.org zawiera łącze do pliku źródłowego, w którym zdefiniowany jest symbol. Docstrings obsługują Markdown i można je (w przybliżeniu) przeglądać za pomocą dowolnej przeglądarki Markdown .

Wersje i gałęzie

Wersja referencyjna interfejsu API witryny to domyślnie najnowszy stabilny plik binarny — odpowiada to pakietowi zainstalowanemu za pomocą pip install tensorflow .

Domyślny pakiet TensorFlow jest zbudowany ze stabilnej gałęzi rX.x w głównym repozytorium tensorflow/tensorflow . Dokumentacja referencyjna jest generowana na podstawie komentarzy kodu i ciągów dokumentów w kodzie źródłowym Pythona , C++ i Java .

Poprzednie wersje dokumentacji TensorFlow są dostępne jako gałęzie rX.x w repozytorium TensorFlow Docs. Te gałęzie są dodawane po wydaniu nowej wersji.

Twórz dokumenty API

Odniesienie do Pythona

Pakiet tensorflow_docs zawiera generator dokumentacji referencyjnej API Pythona . Żeby zainstalować:

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

Aby wygenerować dokumentację referencyjną TensorFlow 2, użyj 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

Dokumentacja narracyjna

Przewodniki i samouczki TensorFlow są napisane jako pliki Markdown i interaktywne notatniki Jupyter . Notatniki można uruchamiać w przeglądarce za pomocą Google Colaboratory . Dokumentacja narracyjna na tensorflow.org jest zbudowana z master gałęzi tensorflow/docs . Starsze wersje są dostępne w GitHub w gałęziach wydania rX.x

Proste zmiany

Najłatwiejszym sposobem na dokonywanie prostych aktualizacji dokumentacji w plikach Markdown jest użycie internetowego edytora plików GitHub . Przejrzyj repozytorium tensorflow/docs , aby znaleźć znacznik Markdown, który w przybliżeniu odpowiada strukturze adresu URL tensorflow.org . W prawym górnym rogu widoku pliku kliknij ikonę ołówka aby otworzyć edytor plików. Edytuj plik, a następnie prześlij nowe żądanie ściągnięcia.

Skonfiguruj lokalne repozytorium Git

W przypadku edycji wielu plików lub bardziej złożonych aktualizacji lepiej jest użyć lokalnego przepływu pracy Git, aby utworzyć żądanie ściągnięcia.

Poniższe kroki Git są wymagane tylko podczas pierwszej konfiguracji projektu lokalnego.

Rozwidlaj repozytorium tensorflow/docs

Na stronie GitHub tensorflow/docs kliknij przycisk Rozwidlaj aby utworzyć własną kopię repozytorium na swoim koncie GitHub. Po rozwidleniu jesteś odpowiedzialny za aktualizowanie swojej kopii repozytorium dzięki wcześniejszemu repozytorium TensorFlow.

Sklonuj swoje repozytorium

Pobierz kopię zdalnego repozytorium username / docs na komputer lokalny. To jest katalog roboczy, w którym będziesz dokonywać zmian:

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

Dodaj repozytorium nadrzędne, aby być na bieżąco (opcjonalnie)

Aby zachować synchronizację lokalnego repozytorium z tensorflow/docs , dodaj pilota nadrzędnego , aby pobrać najnowsze zmiany.

Dodaj pilota:

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)

Aktualizować:

git checkout master
git pull upstream master

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

Przepływ pracy na GitHubie

1. Utwórz nowy oddział

Po zaktualizowaniu repozytorium z tensorflow/docs , utwórz nową gałąź z lokalnej gałęzi master :

git checkout -b feature-name

git branch  # List local branches
  master

* feature-name

2. Wprowadź zmiany

Edytuj pliki w swoim ulubionym edytorze i postępuj zgodnie z przewodnikiem stylu dokumentacji TensorFlow .

Zatwierdź zmianę pliku:

# 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."

W razie potrzeby dodaj więcej zatwierdzeń.

3. Utwórz pull request

Prześlij swój lokalny oddział do zdalnego repozytorium GitHub (github.com/ username /docs):

git push

Po zakończeniu wypychania komunikat może wyświetlać adres URL, aby automatycznie przesłać żądanie ściągnięcia do repozytorium nadrzędnego. Jeśli nie, przejdź do repozytorium tensorflow/docs — lub własnego repozytorium — a GitHub wyświetli monit o utworzenie żądania ściągnięcia.

4. Recenzja

Opiekunowie i inni współtwórcy przejrzą Twoje żądanie ściągnięcia. Prosimy o wzięcie udziału w dyskusji i wprowadzenie żądanych zmian. Gdy Twoje żądanie ściągnięcia zostanie zatwierdzone, zostanie scalone z nadrzędnym repozytorium dokumentów TensorFlow.

Aby zaktualizować tensorflow.org z repozytorium GitHub, istnieje oddzielny krok publikowania. Zazwyczaj zmiany są gromadzone razem, a witryna jest regularnie aktualizowana.

Interaktywne zeszyty

Chociaż można edytować plik JSON notatnika za pomocą internetowego edytora plików GitHub , nie jest to zalecane, ponieważ zniekształcony JSON może uszkodzić plik. Przed przesłaniem żądania ściągnięcia należy przetestować notatnik.

Google Colaboratory to hostowane środowisko notatników, które ułatwia edytowanie i uruchamianie dokumentacji notatnika. Notatniki w GitHub są ładowane w Google Colab poprzez przekazanie ścieżki do adresu URL Colab, na przykład notatnik znajdujący się w GitHub tutaj: https://github.com/tensorflow/docs/blob/master/site/en/tutorials/keras /klasyfikacja.ipynb
można załadować do Google Colab pod tym adresem URL: https://colab.research.google.com/github/tensorflow/docs/blob/master/site/en/tutorials/keras/classification.ipynb

Istnieje rozszerzenie Open in Colab Chrome, które wykonuje tę zamianę adresu URL podczas przeglądania notatnika w serwisie GitHub. Jest to przydatne podczas otwierania notatnika w rozwidleniu repozytorium, ponieważ górne przyciski zawsze łączą się z master gałęzią TensorFlow Docs.

Formatowanie notatnika

Narzędzie do formatowania notatników sprawia, że ​​źródła notatników Jupyter są spójne i łatwiejsze do przeglądania. Ponieważ środowiska tworzenia notatników różnią się pod względem wyjścia pliku, wcięć, metadanych i innych nieokreślonych pól; nbfmt używa upartych wartości domyślnych z preferencją dla przepływu pracy dokumentów TensorFlow Colab. Aby sformatować notatnik, zainstaluj narzędzia notatników TensorFlow docs i uruchom narzędzie 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 [...]

W przypadku projektów dokumentów TensorFlow wykonywane są i testowane notebooki bez komórek wyjściowych; notatniki z zapisanymi komórkami wyjściowymi są publikowane w stanie, w jakim są. nbfmt uwzględnia stan notatnika i używa opcji --remove_outputs do jawnego usuwania komórek wyjściowych.

Aby utworzyć nowy notatnik, skopiuj i edytuj szablon notatnika dokumentów TensorFlow .

Edytuj w Colab

W środowisku Google Colab kliknij dwukrotnie komórki, aby edytować bloki tekstu i kodu. Komórki tekstowe używają języka Markdown i powinny być zgodne z przewodnikiem po stylu dokumentów TensorFlow .

Pobierz pliki notatników z Colab za pomocą opcji Plik > Pobierz .pynb . Zatwierdź ten plik w lokalnym repozytorium Git i wyślij żądanie ściągnięcia.

Aby utworzyć nowy notatnik, skopiuj i edytuj szablon notatnika TensorFlow .

Przepływ pracy w Colab-GitHub

Zamiast pobierać plik notatnika i korzystać z lokalnego przepływu pracy Git, możesz edytować i aktualizować swoje rozwidlone repozytorium GitHub bezpośrednio z Google Colab:

  1. W repozytorium rozwidlonej username /docs użyj interfejsu internetowego GitHub, aby utworzyć nową gałąź .
  2. Przejdź do pliku notatnika do edycji.
  3. Otwórz notatnik w Google Colab: użyj zamiany adresów URL lub rozszerzenia Otwórz w Colab Chrome.
  4. Edytuj notatnik w Colab.
  5. Zatwierdź zmiany w repozytorium z Colab za pomocą opcji Plik > Zapisz kopię w GitHub... . Okno dialogowe zapisywania powinno łączyć się z odpowiednim repozytorium i gałęzią. Dodaj zrozumiałą wiadomość o zatwierdzeniu.
  6. Po zapisaniu przejdź do swojego repozytorium lub repozytorium tensorflow/docs , GitHub powinien wyświetlić monit o utworzenie żądania ściągnięcia.
  7. Żądanie ściągnięcia jest sprawdzane przez opiekunów.

Tłumaczenia

Zespół TensorFlow współpracuje ze społecznością i dostawcami, aby zapewnić tłumaczenia dla tensorflow.org. Tłumaczenia notatników i innych treści technicznych znajdują się w repozytorium tensorflow/docs-l10n GitHub. Prześlij żądania ściągnięcia za pośrednictwem projektu TensorFlow GitLocalize .

Angielskie dokumenty są źródłem prawdy, a tłumaczenia powinny być zgodne z tymi przewodnikami tak blisko, jak to możliwe. To powiedziawszy, tłumaczenia są pisane dla społeczności, którym służą. Jeśli angielska terminologia, fraza, styl lub ton nie przekładają się na inny język, prosimy o skorzystanie z tłumaczenia odpowiedniego dla czytelnika.

Obsługa języka zależy od wielu czynników, w tym między innymi od wskaźników i popytu w witrynie, wsparcia społeczności, znajomości języka angielskiego , preferencji odbiorców i innych wskaźników. Ponieważ każdy obsługiwany język wiąże się z kosztami, nieobsługiwane języki są usuwane. Wsparcie dla nowych języków zostanie ogłoszone na blogu TensorFlow lub na Twitterze .

Jeśli preferowany język nie jest obsługiwany, możesz prowadzić fork społecznościowy dla współtwórców open source. Nie są one publikowane na tensorflow.org.