Google is committed to advancing racial equity for Black communities. See how.
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 najnowszy stabilny plik binarny - jest to zgodne z pakietem zainstalowanym za pomocą narzędzia pip install tensorflow .

Domyślny pakiet TensorFlow jest budowany na podstawie 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 master gałęzi 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 własnego repozytorium - a GitHub poprosi Cię 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. Gdy żą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ą 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 w serwisie 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 wspólnotowe

Tłumaczenia społecznościowe to świetny sposób na udostępnienie TensorFlow na całym świecie. Aby zaktualizować tłumaczenie, znajdź lub dodaj plik w katalogu językowym, który pasuje do tej samej struktury katalogów w katalogu en/ . 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.

Istnieją grupy dokumentów dla poszczególnych języków, które ułatwiają organizowanie się tłumaczom. Dołącz, jeśli jesteś autorem, recenzentem lub po prostu chcesz tworzyć treści TensorFlow.org dla społeczności:

Przejrzyj powiadomienia

Wszystkie aktualizacje dokumentacji wymagają przeglądu. Aby efektywniej współpracować ze społecznościami tłumaczy TensorFlow, oto kilka sposobów na śledzenie działań specyficznych dla języka:

  • Dołącz do grupy językowej wymienionej powyżej, aby otrzymać wiadomość e-mail z każdym utworzonym żądaniem ściągnięcia, które dotyczy katalogu site/ lang dla tego języka.
  • Dodaj swoją nazwę użytkownika GitHub do pliku site/<lang>/REVIEWERS , aby uzyskać automatyczne oznaczenie komentarza w żądaniu ściągnięcia. Po oznaczeniu komentarza GitHub wyśle ​​powiadomienia o wszystkich zmianach i dyskusji w tym żądaniu ściągnięcia.

Aktualizuj kod w tłumaczeniach

W przypadku projektów typu open source, takich jak TensorFlow, utrzymanie aktualności dokumentacji jest trudne. Po rozmowie ze społecznością czytelnicy przetłumaczonych treści będą tolerować tekst, który jest trochę nieaktualny, ale nieaktualny kod jest frustrujący. Aby ułatwić synchronizację kodu, użyj narzędzia nb-code-sync dla przetłumaczonych notatników:

./tools/nb_code_sync.py [--lang=en] site/lang/notebook.ipynb

Ten skrypt odczytuje komórki kodu z notatnika językowego i porównuje go z wersją angielską. Po usunięciu komentarzy porównuje bloki kodu i aktualizuje notatnik językowy, jeśli są różne. To narzędzie jest szczególnie przydatne w interaktywnym przepływie pracy git, aby selektywnie dodawać fragmenty pliku do zatwierdzenia za pomocą: git add --patch site/lang/notebook.ipynb