Współtwórz dokumentację TensorFlow

TensorFlow chętnie 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 obok kodu w oddzielnym repozytorium, zwykle w katalogu docs/ . Zobacz plik CONTRIBUTING.md projektu lub skontaktuj się z opiekunem, aby wniósł wkład.

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

Odniesienie do API

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

Wersje i gałęzie

Domyślną wersją referencyjną interfejsu API witryny jest 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 do kodu i ciągów dokumentów w kodzie źródłowym języków Python , C++ i Java .

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

Twórz dokumenty API

Odniesienie do Pythona

Pakiet tensorflow_docs zawiera generator dokumentacji referencyjnej API języka Python . Aby zainstalować:

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

Aby wygenerować dokumentację referencyjną TensorFlow 2, użyj skryptu 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ą zapisywane jako pliki Markdown i interaktywne notatniki Jupyter . Notatniki można uruchamiać w przeglądarce za pomocą Google Colaboratory . Dokumenty narracyjne na tensorflow.org są zbudowane z master gałęzi tensorflow/docs . Starsze wersje są dostępne w GitHub w gałęziach wydań rX.x

Proste zmiany

Najłatwiejszym sposobem na dokonanie prostych aktualizacji dokumentacji plików 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 przy pierwszej konfiguracji projektu lokalnego.

Rozwiń repozytorium tensorflow/docs

Na stronie tensorflow/docs GitHub kliknij przycisk Fork aby utworzyć własną kopię repo na swoim koncie GitHub. Po rozwidleniu jesteś odpowiedzialny za aktualizowanie kopii repozytorium za pomocą wcześniejszego repozytorium TensorFlow.

Sklonuj swoje repozytorium

Pobierz kopię swojego zdalnego repozytorium username /docs na komputer lokalny. To jest katalog roboczy, w którym dokonasz 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)

Aby zaktualizować: 

git checkout master
git pull upstream master

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

Przepływ pracy w GitHubie

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

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

git push

Po zakończeniu przesyłania komunikat może wyświetlić adres URL umożliwiający automatyczne przesłanie żądania ściągnięcia do repozytorium nadrzędnego. Jeśli nie, przejdź do repozytorium tensorflow/docs — lub do własnego repozytorium — a GitHub poprosi Cię o utworzenie żądania ściągnięcia.

4. Przegląd

Opiekunowie i inni współpracownicy przejrzą Twoją prośbę o ściągnięcie. Prosimy o udział w dyskusji i wprowadzenie żądanych zmian. Po zatwierdzeniu żądania ściągnięcia zostanie ono połączone z nadrzędnym repozytorium dokumentów TensorFlow.

Aktualizacja tensorflow.org z repozytorium GitHub wymaga osobnego etapu publikowania. Zazwyczaj zmiany są grupowane i witryna jest aktualizowana w regularnym tempie.

Interaktywne notesy

Chociaż można edytować plik JSON notesu za pomocą internetowego edytora plików GitHub, nie jest to zalecane, ponieważ zniekształcony plik JSON może spowodować uszkodzenie pliku. Przed przesłaniem żądania ściągnięcia pamiętaj o przetestowaniu notebooka.

Google Colaboratory to hostowane środowisko notatników, które ułatwia edytowanie i uruchamianie dokumentacji notatników. Notatniki w GitHub ładuje się w Google Colab poprzez podanie ś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 podstawianie tego adresu URL podczas przeglądania notatnika w GitHub. Jest to przydatne podczas otwierania notatnika w forku repo, ponieważ górne przyciski zawsze prowadzą do master gałęzi TensorFlow Docs.

Formatowanie notatnika

Narzędzie do formatowania notatnika sprawia, że ​​różnice w źródłach notatnika Jupyter są spójne i łatwiejsze do przeglądania. Ponieważ środowiska tworzenia notatników różnią się pod względem danych wyjściowych plików, wcięć, metadanych i innych nieokreślonych pól; nbfmt używa ustalonych wartości domyślnych, preferując przepływ pracy w TensorFlow docs Colab. Aby sformatować notatnik, zainstaluj narzędzia notatnika dokumentów TensorFlow 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 i testowane są notesy bez komórek wyjściowych; notesy z zapisanymi komórkami wyjściowymi są publikowane w niezmienionej postaci. nbfmt szanuje stan notatnika i używa opcji --remove_outputs , aby jawnie usuwać komórki wyjściowe.

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

Edytuj w Colabie

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

Pobierz pliki notatników z Colab za pomocą opcji Plik > Pobierz plik .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ć rozwidlone repozytorium GitHub bezpośrednio z Google Colab:

  1. W rozwidlonym repozytorium username /docs 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 adresów URL lub rozszerzenia Otwórz w Colab do Chrome.
  4. Edytuj notatnik w Colab.
  5. Zatwierdź zmiany w repozytorium z Colab za pomocą opcji Plik > Zapisz kopię w GitHub... . Okno zapisu powinno zawierać link do odpowiedniego repozytorium i gałęzi. Dodaj znaczący komunikat zatwierdzenia.
  6. Po zapisaniu przejdź do 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 innej zawartości technicznej znajdują się w repozytorium GitHub tensorflow/docs-l10n . Proszę przesłać żądania ściągnięcia za pośrednictwem projektu TensorFlow GitLocalize .

Dokumentacja w języku angielskim jest źródłem prawdy i tłumaczenia powinny być jak najbardziej zgodne z tymi przewodnikami. To powiedziawszy, tłumaczenia są pisane dla społeczności, którym służą. Jeżeli angielska terminologia, sformułowania, styl lub ton nie dają się przełożyć na inny język, prosimy użyć tłumaczenia odpowiedniego dla czytelnika.

Wsparcie językowe zależy od wielu czynników, w tym między innymi wskaźników witryny i popytu, 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, języki nieobsługiwane są usuwane. Wsparcie dla nowych języków zostanie ogłoszone na blogu TensorFlow lub Twitterze .

Jeśli preferowany przez Ciebie język nie jest obsługiwany, możesz utrzymać fork społeczności dla współpracowników open source. Nie są one publikowane na tensorflow.org.