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

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

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

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

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

• Посмотрите репозиторий tensorflow/docs на GitHub.
• Следуйте тегу документации на форуме 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

Примечание. Этот шаг не требуется для редактирования или предварительного просмотра строк документации API, он необходим только для создания HTML, используемого на tensorflow.org.

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

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

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 для создания документов и работает только для TensorFlow 2.x.

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

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

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

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

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

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

Примечание. Git — это система контроля версий с открытым исходным кодом (VCS), используемая для отслеживания изменений в исходном коде. GitHub — это онлайн-сервис, предоставляющий инструменты для совместной работы, работающие с Git. См. справку GitHub, чтобы настроить учетную запись GitHub и начать работу.

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

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

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

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

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

git clone [e-mail]:username/docs
cd ./docs

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

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

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

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

git remote add upstream [e-mail]:tensorflow/docs.git

# View remote repos
git remote -v
origin    [e-mail]:username/docs.git (fetch)
origin    [e-mail]:username/docs.git (push)
upstream  [e-mail]:tensorflow/docs.git (fetch)
upstream  [e-mail]: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

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

4. Обзор

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

Успех: ваши изменения в документации 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. Чтобы отформатировать записную книжку, установите инструменты записной книжки TensorFlow 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 .

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

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

Загрузите файлы блокнотов из Colab, выбрав «Файл» > «Загрузить .pynb» . Зафиксируйте этот файл в своем локальном репозитории Git и отправьте запрос на включение.

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

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

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

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

Успех: ваши изменения в документации TensorFlow приняты.

Переводы

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

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

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

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