Google is committed to advancing racial equity for Black communities. See how.

Внесите вклад в документацию TensorFlow

TensorFlow приветствует вклад в документацию - если вы улучшите документацию, вы улучшите саму библиотеку TensorFlow. Документация на tensorflow.org подразделяется на следующие категории:

Некоторые проекты TensorFlow хранят исходные файлы документации рядом с кодом в отдельном репозитории, обычно в каталоге docs/ . См. Файл CONTRIBUTING.md проекта или свяжитесь с сопровождающим, чтобы внести свой вклад.

Чтобы принять участие в сообществе документации TensorFlow:

Справочник по API

Для обновления справочной документации, найти исходный файл и изменение символа в строке документации . Многие справочные страницы API на tenorflow.org включают ссылку на исходный файл, в котором определен символ. Строки документации поддерживают Markdown и могут быть (приблизительно) предварительно просмотрены с помощью любого средства предварительного просмотра Markdown .

Чтобы узнать о качестве справочной документации и о том, как принять участие в спринтах документации и сообществе, см. Совет TensorFlow 2 API Docs .

Версии и ветки

В качестве эталонной версии API сайта по умолчанию используется последний стабильный двоичный файл - он соответствует пакету, установленному с помощью pip install tensorflow .

Пакет rX.x по умолчанию создается из стабильной ветки rX.x в основном репозитории tenorflow / tensorflow . Справочная документация создается из комментариев к коду и строк документации в исходном коде для Python , C ++ и Java .

Предыдущие версии документации TensorFlow доступны в виде веток rX.x в репозитории TensorFlow Docs. Эти ветки добавляются при выпуске новой версии.

Документация по API сборки

Справочник по Python

Пакет tensorflow_docs включает генератор справочной документации Python API . Установить:

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

Чтобы создать справочную документацию tensorflow/tools/docs/generate2.py 2, используйте 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

Описательная документация

Руководства и учебные пособия TensorFlow написаны в виде файлов Markdown и интерактивных блокнотов Jupyter . Записные книжки можно запускать в браузере с помощью Google Colaboratory . Описательная документация на tenorflow.org построена на основе ветки tenorflow / docs master . Более старые версии доступны на GitHub в rX.x выпуска rX.x

Простые изменения

Самый простой способ напрямую обновлять документацию для файлов Markdown - использовать веб-редактор файлов GitHub. Просмотрите репозиторий tensorflow / docs и найдите Markdown, который примерно соответствует структуре URL-адреса tensorflow.org . В правом верхнем углу окна просмотра файлов щелкните значок карандаша , чтобы открыть редактор файлов. Отредактируйте файл, а затем отправьте новый запрос на перенос.

Настроить локальное репозиторий Git

Для редактирования нескольких файлов или более сложных обновлений лучше использовать локальный рабочий процесс Git для создания запроса на перенос.

Следующие шаги Git требуются только при первой настройке локального проекта.

Форк репозитория tensorflow / docs

На странице tenorflow / docs GitHub нажмите кнопку Fork чтобы создать свою собственную копию репо под вашей учетной записью GitHub. После разветвления вы несете ответственность за поддержание актуальности своей копии репо с помощью вышестоящего репозитория TensorFlow.

Клонируйте свое репо

Загрузить копию удаленного username / документы репо на вашу локальную машину. Это рабочий каталог, в котором вы будете вносить изменения:

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

Добавьте вышестоящее репо, чтобы быть в курсе (необязательно)

Чтобы ваш локальный репозиторий синхронизировался с tensorflow/docs , добавьте восходящий пульт для загрузки последних изменений.

Добавьте пульт:

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)

Обновить:

git checkout master
git pull upstream master

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

Рабочий процесс GitHub

1. Создайте новую ветку

После обновления репо из tensorflow/docs создайте новую ветку из локальной главной ветки:

git checkout -b feature-name

git branch  # List local branches
  master

* feature-name

2. Внесите изменения

Отредактируйте файлы в своем любимом редакторе и следуйте руководству по стилю документации TensorFlow .

Зафиксируйте изменение файла:

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

При необходимости добавьте больше коммитов.

3. Создайте запрос на вытягивание.

Загрузите локальную ветку в удаленное репозиторий GitHub (github.com/ username / docs):

git push

После завершения push в сообщении может отображаться URL-адрес для автоматической отправки запроса на вытягивание в вышестоящее репо. Если нет, перейдите в репозиторий tensorflow / docs или в собственное репо, и GitHub предложит вам создать запрос на перенос .

4. Обзор

Сопровождающие и другие участники рассмотрят ваш запрос на включение. Пожалуйста, примите участие в обсуждении и внесите требуемые изменения. Когда ваш запрос на вытягивание будет одобрен, он будет объединен с вышестоящим репозиторием документации TensorFlow.

Существует отдельный этап публикации для обновления tensorflow.org из репозитория GitHub. Обычно изменения группируются вместе, и сайт обновляется регулярно.

Интерактивные записные книжки

Хотя можно редактировать файл JSON записной книжки с помощью веб-редактора файлов GitHub, это не рекомендуется, поскольку искаженный JSON может повредить файл. Обязательно проверьте ноутбук перед отправкой запроса на перенос.

Google Colaboratory - это размещенная среда для записных книжек, которая упрощает редактирование и запуск документации для записных книжек. Блокноты в GitHub загружаются в Google Colab путем передачи пути к URL-адресу Colab, например блокнот, расположенный в GitHub здесь: https://github.com/tensorflow/docs/blob/master/site/en/tutorials/keras /classification.ipynb
можно загрузить в Google Colab по этому URL-адресу: https://colab.research.google.com/github/tensorflow/docs/blob/master/site/en/tutorials/keras/classification.ipynb

Существует расширение Open in Colab для Chrome, которое выполняет эту подстановку URL-адресов при просмотре записной книжки на GitHub. Это полезно при открытии записной книжки в вилке репо, потому что верхние кнопки всегда ссылаются на master ветку TensorFlow Docs.

Форматирование записной книжки

Инструмент форматирования записных книжек делает исходные тексты записных книжек Jupyter единообразными и удобными для просмотра. Поскольку среды разработки записных книжек различаются в отношении вывода файлов, отступов, метаданных и других неуказанных полей; nbfmt использует самоуверенные значения по умолчанию, отдавая предпочтение рабочему процессу Colab в документации TensorFlow. Чтобы отформатировать записную книжку, установите инструменты записной книжки nbfmt docs и запустите инструмент 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 [...]

Для проектов документации TensorFlow выполняются и тестируются записные книжки без ячеек вывода; записные книжки с сохраненными ячейками вывода публикуются как есть. nbfmt учитывает состояние записной книжки и использует параметр --remove_outputs для явного удаления выходных ячеек.

Чтобы создать новую записную книжку, скопируйте и отредактируйте шаблон записной книжки TensorFlow docs .

Редактировать в Colab

В среде Google Colab дважды щелкните ячейки, чтобы редактировать текст и блоки кода. Текстовые ячейки используют Markdown и должны соответствовать руководству по стилю документации TensorFlow .

Загрузите файлы записной книжки из Colab с помощью File> Download .pynb . Зафиксируйте этот файл в своем локальном репозитории Git и отправьте запрос на перенос.

Чтобы создать новую записную книжку, скопируйте и отредактируйте шаблон записной книжки TensorFlow .

Рабочий процесс Colab-GitHub

Вместо того, чтобы загружать файл записной книжки и использовать локальный рабочий процесс Git, вы можете редактировать и обновлять разветвленное репозиторий GitHub прямо из Google Colab:

  1. В репозитории с разветвленным username / документами используйте веб-интерфейс GitHub для создания новой ветки .
  2. Перейдите к файлу записной книжки для редактирования.
  3. Откройте записную книжку в Google Colab: используйте замену URL или расширение Open in Colab Chrome.
  4. Отредактируйте записную книжку в Colab.
  5. Зафиксируйте изменения в своем репо из Colab, выбрав « Файл»> «Сохранить копию в GitHub ...» . Диалог сохранения должен ссылаться на соответствующее репо и ветку. Добавьте содержательное сообщение о фиксации.
  6. После сохранения перейдите в свое репо или репозиторий tensorflow / docs , GitHub должен предложить вам создать запрос на перенос .
  7. Запрос на вытягивание проверяется сопровождающими.

Переводы

Команда TensorFlow работает с сообществом и поставщиками, чтобы предоставить переводы для tenorflow.org. Переводы записных книжек и другого технического контента находятся в репозитории tenorflow / docs-l10n на GitHub. Отправляйте запросы на вытягивание через проект TensorFlow GitLocalize .

Документы на английском языке являются источником правды, и переводы должны как можно точнее следовать этим руководствам. Тем не менее, переводы написаны для сообществ, которым они служат. Если английская терминология, фразы, стиль или тон не переводятся на другой язык, пожалуйста, используйте перевод, подходящий для читателя.

Языковая поддержка определяется рядом факторов, включая, помимо прочего, показатели и спрос на сайте, поддержку сообщества, уровень владения английским языком , предпочтения аудитории и другие показатели. Поскольку каждый поддерживаемый язык требует затрат, неподдерживаемые языки удаляются. О поддержке новых языков будет объявлено в блоге TensorFlow или в Twitter .

Если предпочитаемый вами язык не поддерживается, вы можете создать вилку сообщества для участников с открытым исходным кодом. Они не публикуются на tenorflow.org.