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

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

• Справочник по API — Справочные документы по API генерируются из строк документации в исходном коде TensorFlow .
• Описательная документация — это учебные пособия , руководства и другая документация, не являющаяся частью кода TensorFlow. Эта документация находится в репозитории tensorflow/docs на GitHub.
• Переводы сообщества — это руководства и учебные пособия, переведенные сообществом. Все переводы сообщества находятся в репозитории tensorflow/docs .

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

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

• Посмотрите репозиторий tensorflow/docs на GitHub.
• Следите за тегом docs на форуме TensorFlow .

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

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

Версии и ответвления

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

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

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

Создавайте документы API

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

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

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

Чтобы сгенерировать справочные документы TensorFlow 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 . Описательные документы на tensorflow.org созданы из master ветки tensorflow/docs . Более старые версии доступны на GitHub в ветках выпуска rX.x

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

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

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

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

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

Разветвить репозиторий tensorflow/docs

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

Клонировать репозиторий

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

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 ( username ):

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

Редактировать в Колабе

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

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

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

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

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

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

Переводы

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

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

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

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