Help protect the Great Barrier Reef with TensorFlow on Kaggle Join Challenge

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 zachować pliki źródłowe dokumentacji pobliżu kodu w oddzielnym repozytorium, zwykle w docs/ katalogu. Zobacz projektu CONTRIBUTING.md plik lub skontaktuj się z opiekunem do tego przyczynić.

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

Dokumentacja API

Aby uzyskać szczegółowe informacje, należy użyć Dokumentacja API przewodnik kontrybutora TensorFlow . To pokazuje, jak znaleźć pliku źródłowego i edytować symbolu docstring . Wiele stron referencyjnych API na tensorflow.org zawiera łącze do pliku źródłowego, w którym zdefiniowany jest symbol. Docstrings wspierać Markdown i może być (w przybliżeniu) stronę za pomocą dowolnego przeglądarkę plików Markdown .

Wersje i gałęzie

Witryna jest odniesienie API wersja domyślnie do najnowszej stabilnej binarnie to odpowiada zainstalowany pakiet z pip install tensorflow .

Domyślną pakiet TensorFlow jest zbudowana z gałęzi stabilnej rX.x w głównym tensorflow / tensorflow repo. Dokumentacja referencyjna jest generowana z kodu komentarze i docstrings w kodzie źródłowym Python , C ++ i Java .

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

Twórz dokumenty API

Odniesienie do Pythona

tensorflow_docs pakiet zawiera generator dla Dokumenty interfejsie API Pythona . Żeby zainstalować:

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

Aby wygenerować dokumenty referencyjne TensorFlow 2, użyj tensorflow/tools/docs/generate2.py skrypt:

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

TensorFlow prowadnice i samouczki są zapisywane jako Przecena plików i interaktywnych Jupyter notebooków. Notebooki mogą być uruchamiane w przeglądarce przy użyciu Google Colaboratory . Narracja Docs na tensorflow.org są zbudowane z tensorflow / docs master gałęzi. Starsze wersje są dostępne w GitHub na rX.x oddziałów uwalnianiu.

Proste zmiany

Najprostszym sposobem, aby dokonać aktualizacji proste dokumentacji do plików Markdown jest użycie GitHub za internetowy edytor plików . Przeglądać tensorflow / docs repozytorium znaleźć Markdown, które z grubsza odpowiada tensorflow.org strukturze URL. 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 tensorflow / docs strony GitHub, kliknij przycisk Fork 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 username / docs repo na komputerze lokalnym. 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 utrzymać się z lokalnym repozytorium w synchronizacji z tensorflow/docs , dodać upstream 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 na GitHubie

1. Utwórz nowy oddział

Po zaktualizowaniu repo z tensorflow/docs , tworzyć nowy oddział z lokalnego oddziału głównego:

git checkout -b feature-name

git branch  # List local branches
  master

* feature-name

2. Wprowadź zmiany

Edycja plików w swoim ulubionym edytorze i proszę przestrzegać instrukcji stylu dokumentacja 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 GitHub repo (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 tensorflow / docs repo albo własne repo-a GitHub poprosi, aby utworzyć żądanie ciągnąć.

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.

Istnieje oddzielny krok do publikowania aktualizacji tensorflow.org z repo GitHub. Zazwyczaj zmiany są gromadzone razem, a witryna jest regularnie aktualizowana.

Interaktywne notatniki

O ile to możliwe, aby edytować plik JSON notebook z GitHub za internetowy edytor plików , nie jest zalecane, ponieważ zniekształconych JSON może zaburzyć ten plik. Przed przesłaniem żądania ściągnięcia należy przetestować notatnik.

Google Colaboratory jest gospodarzem środowiska notebook, który umożliwia łatwe i dokumentacji edit-run-notebooków. Notebooki w GitHub są ładowane w Google Colab przekazując ścieżkę do Colab URL, na przykład, komputer znajduje 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 adresem URL: https://colab.research.google.com/github/tensorflow/docs/blob/master/site/en/tutorials/keras/classification.ipynb

Jest otwarta w Colab rozszerzenie Chrome, który wykonuje ten URL podstawienie podczas przeglądania notebooka na GitHub. Funkcja ta jest przydatna podczas otwierania notebooka w repo widelec, ponieważ górne przyciski zawsze odwołują się do TensorFlow Docs master gałęzi.

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 zastosowania opinionated domyślne z preferencją dla docs TensorFlow Colab pracy. Aby sformatować notebooka zainstalować TensorFlow narzędzi docs notebook i uruchom nbfmt narzędzia:

# 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 TensorFlow Dokumenty, notebooki bez komórek wyjściowych są wykonywane i badane; notebooki z zapisanych komórek wyjściowych publikowane są tak jak są. nbfmt szanuje stan notebooka i używa --remove_outputs opcję jawnie usunięcia komórek wyjściowych.

Aby utworzyć nowy notebook, kopiować i edytować TensorFlow szablon docs notebooka .

Edytuj w Colab

W środowisku Google Colab kliknij dwukrotnie komórki, aby edytować bloki tekstu i kodu. Komórki tekstowe używać Markdown i powinien przestrzegać instrukcji TensorFlow docs stylu .

Pliki do pobrania notebook Colab z Plik> Pobierz .pynb. Popełnić ten plik na dysku lokalnym repo Git i wysłać żądanie ciągnąć.

Aby utworzyć nowy notebook, kopiować i edytować szablon notatnik 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 repozytorium rozwidlone GitHub bezpośrednio z Google Colab:

  1. W swojej rozwidlony username / docs repo, narzędzia Web UI GitHub aby utworzyć nowy oddział .
  2. Przejdź do pliku notatnika do edycji.
  3. Otwórz notatnik w Google Colab: użyj swap URL lub Otwórz w rozszerzeniu Colab Chrome.
  4. Edytuj notatnik w Colab.
  5. Zatwierdzić zmiany do repo z Colab z menu 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 swojej repo lub tensorflow / docs repo, GitHub powinny skłonić cię do tworzenia żądania ciągnąć.
  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 innych materiałów technicznych znajdują się w tensorflow / docs-l10n GitHub repo. Proszę składać wnioski ciągnąć przez projekcie TensorFlow GitLocalize .

Angielscy docs są źródłem-of-prawdy i tłumaczenia należy wykonać następujące prowadnice 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, ale nie ograniczając się do metryki miejscu i popytu, wsparcie wspólnotowe, 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ęzykach zostaną ogłoszone na blogu TensorFlow lub Twitter .

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.