Save the date! Google I/O returns May 18-20 Register now
Ta strona została przetłumaczona przez Cloud Translation API.
Switch to English

Wspieraj dokumentację TensorFlow

TensorFlow z zadowoleniem przyjmuje wkład w postaci dokumentacji - poprawiając dokumentację, ulepszasz 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 oddzielnym repozytorium, zwykle w katalogu docs/ . Zobacz plik CONTRIBUTING.md projektu lub skontaktuj się z opiekunem w celu wniesienia wkładu.

Aby uczestniczyć w społeczności dokumentów TensorFlow:

Dokumentacja API

Aby zaktualizować dokumentację referencyjną, znajdź plik źródłowy i edytować symbolu docstring . Wiele stron z informacjami o API na tensorflow.org zawiera odsyłacz do pliku źródłowego, w którym zdefiniowano symbol. Docstrings obsługują Markdown i można je (w przybliżeniu) przeglądać za pomocą dowolnej przeglądarki Markdown .

Aby uzyskać informacje o jakości dokumentacji referencyjnej oraz o tym, jak zaangażować się w sprint dokumentów i społeczność, zobacz porady TensorFlow 2 API Docs .

Wersje i gałęzie

Wersja referencyjna interfejsu API witryny jest domyślnie ustawiona na najnowszą stabilną wersję binarną - odpowiada to pakietowi zainstalowanemu za pomocą narzędzia pip install tensorflow .

Domyślny pakiet TensorFlow jest budowany z stabilnej gałęzi rX.x w głównym repozytorium tensorflow / tensorflow . Dokumentacja referencyjna jest generowana na podstawie komentarzy do kodu i ciągów dokumentów w kodzie źródłowym dla języków Python , 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

Dokumentacja w Pythonie

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

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

Aby wygenerować dokumenty referencyjne 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 gałęzi master tensorflow / docs . Starsze wersje są dostępne w GitHub w rX.x wydania rX.x

Proste zmiany

Najłatwiejszym sposobem na wprowadzenie prostych aktualizacji dokumentacji do plików Markdown jest użycie internetowego edytora plików GitHub. Przejrzyj repozytorium tensorflow / docs, aby znaleźć Markdown, który z grubsza 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 do utworzenia żądania ściągnięcia.

Poniższe kroki Git są wymagane tylko podczas pierwszego konfigurowania projektu lokalnego.

Rozwidlaj repozytorium tensorflow / docs

Na stronie tensorflow / docs GitHub kliknij przycisk Rozwidlenie aby utworzyć własną kopię repozytorium na koncie GitHub. Po rozwidleniu jesteś odpowiedzialny za aktualizowanie kopii repozytorium za pomocą nadrzędnego repozytorium TensorFlow.

Sklonuj repozytorium

Pobierz kopię zdalnego username / docs repo na komputerze lokalnym. To jest katalog roboczy, w którym dokonasz zmian:

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

Dodaj zewnętrzne repozytorium, aby być na bieżąco (opcjonalnie)

Aby zachować synchronizację lokalnego repozytorium z tensorflow/docs , dodaj nadrzędnego pilota, 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 w GitHub

1. Utwórz nowy oddział

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

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 stylistycznym 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 żądanie ściągnięcia

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

git push

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

4. Przejrzyj

Opiekunowie i inni współpracownicy sprawdzą Twoją prośbę o ściągnięcie. Proszę wziąć udział w dyskusji i wprowadzić wymagane zmiany. Po zatwierdzeniu żądania ściągnięcia zostanie ono scalone z nadrzędnym repozytorium dokumentów TensorFlow.

Aby zaktualizować tensorflow.org z repozytorium GitHub, istnieje oddzielny krok publikowania. Zazwyczaj zmiany są grupowane 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ż źle sformułowany plik JSON może uszkodzić plik. Pamiętaj, aby przetestować notebook przed przesłaniem żądania ściągnięcia.

Google Colaboratory to hostowane środowisko notatników, które ułatwia edycję - i uruchamianie - dokumentacji notebooków. Notatniki w GitHub są ładowane w Google Colab, przekazując ścieżkę 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 /classification.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 do przeglądarki Chrome, które wykonuje tę zamianę adresu URL podczas przeglądania notebooka na GitHub. Jest to przydatne podczas otwierania notatnika w widełkach repozytorium, ponieważ górne przyciski zawsze prowadzą do master gałęzi TensorFlow Docs.

Formatowanie notatnika

Narzędzie do formatowania notatników sprawia, że ​​różnice źródłowe notatników Jupyter są spójne i łatwiejsze do przejrzenia. Ponieważ środowiska tworzenia notatników różnią się pod względem danych wyjściowych pliku, wcięć, metadanych i innych nieokreślonych pól; nbfmt używa upartych wartości domyślnych z preferencją dla przepływu pracy TensorFlow docs Colab. Aby sformatować notatnik, zainstaluj narzędzia notatnika 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 dokumentacyjnych TensorFlow notebooki bez komórek wyjściowych są wykonywane i testowane; notatniki z zapisanymi komórkami wyjściowymi są publikowane w stanie, w jakim się znajdują. nbfmt szanuje stan notatnika i używa opcji --remove_outputs , aby jawnie usunąć komórki wyjściowe.

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

Edytuj w Colab

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

Pobierz pliki notatników z Colab za pomocą 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 Colab-GitHub

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

  1. W repozytorium rozwidlonych username / dokumentów użyj interfejsu internetowego GitHub, aby utworzyć nową gałąź .
  2. Przejdź do pliku notatnika, który chcesz edytować.
  3. Otwórz notatnik w Google Colab: użyj zamiany adresu URL lub rozszerzenia Open in Colab Chrome.
  4. Edytuj notatnik w Colab.
  5. Zatwierdź zmiany w swoim repozytorium z Colab za pomocą Plik> Zapisz kopię w GitHub .... Okno dialogowe zapisywania powinno zawierać łącze do odpowiedniego repozytorium i gałęzi. Dodaj zrozumiały komunikat o zatwierdzeniu.
  6. Po zapisaniu przejdź do repozytorium lub repozytorium tensorflow / docs , GitHub powinien poprosić 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 notebooków i inne treści techniczne 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 dokładnie, 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, proszę użyć tłumaczenia odpowiedniego dla czytelnika.

Obsługa języków zależy od wielu czynników, w tym między innymi wskaźników i popytu na stronie, 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 Twitterze .

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