GitHub и Read The Docs

В главе описывается взаимодействие двух сервисов и приводятся рекомендации по их настройке.

Работа с GitHub

GitHub обладает богатым набором функций. В данном разделе будут описаны только основные функции, необходимые для совместной работы над документацией. За дополнительной информацией обратитесь к следующим материалам:

Что такое GitHub

GitHub (https://github.com) — веб-сервис для хостинга IT-проектов и их совместной разработки, основанный на системе контроля версий Git. Сервис абсолютно бесплатен для проектов с открытым исходным кодом. Для создания закрытых проектов предлагаются различные платные тарифные планы.

GitHub позволяет:

  • Размещать исходный код программ;
  • Комментировать и обсуждать правки;
  • Следить за обновлениями проектов;
  • Копировать и скачивать репозитории проектов;
  • Объединять репозитории;
  • Создавать небольшие Вики проектов;
  • Редактировать файлы непосредственно через веб-интерфейс;
  • Создавать статичные HTML-страницы проектов;
  • Для платных аккаунтов доступно создание приватных репозиториев, доступных ограниченному кругу пользователей.

Кроме Git, сервис поддерживает получение и редактирование кода через SVN и Mercurial.

Также на сайте есть pastebin-сервис gist.github.com для быстрой публикации фрагментов кода.

Для комфортной работы с GitHub, необходимо уметь работать с системой контроля версий Git, подробнее смотрите главу Система управления версиями Git.

Регистрация

Процедура регистрации проста, бесплатна и не занимает много времени. Достаточно заполнить три поля: логин, адрес электронной почты и пароль. На почту будет выслан запрос на подтверждение регистрации.

Процедура регистрации на GitHub

Создание репозитория

GitHub — это не простой хостинг файлов, он завязан на систему управления версиями файлов и служит для выгрузки локальных пользовательских git-репозиториев.

Для создания репозитория нажмите значок + и выберите пункт New repository.

GitHub: Создание нового репозитория. Шаг 1.

Будет открыта страница, на которой задается название репозитория и его описание.

GitHub: Создание нового репозитория. Шаг 2.

Чтобы создать новый репозиторий на компьютере и выгрузить его в репозиторий на GitHub, выполните в командной строке:

touch README.md
git init
git add README.md
git commit -m "first commit"
git remote add origin https://github.com/LibreRussia/my-project.git
git push -u origin master

Note

Используйте URL-адрес вашего репозитория для команды remote.

Чтобы выгрузить в репозиторий на GitHub уже существующий репозиторий выполните в командной строке:

git remote add origin https://github.com/LibreRussia/my-project.git
git push -u origin master
GitHub: Создание нового репозитория. Шаг 3.

Выгружать файлы в репозиторий на GitHub могут только те пользователи, которые имеют право на запись. Загрузить же копию репозитория на компьютер может любой пользователей, если это не ограничено настройками приватности репозитория (доступно в платных тарифах).

Также имеется возможность создавать совместные для нескольких аккаунтов репозитории. В целях безопасности я предпочитаю не давать никому доступ к основному репозиторию и работаю через систему форков (см. Копирование репозитория (Fork)).

Копирование репозитория (Fork)

Любой желающий может сделать полную копию(англ. Fork — разветвление) чужого репозитория и работать над ней независимо от основного. После внесения всех изменений, можно предложить их в основной репозиторий (сделать, так называемый, Pull Requests).

Чтобы создать форк, необходимо зайти в репозиторий и нажать кнопку Fork.

GitHub: Создание копии репозитория.

После чего в аккаунте пользователя появится полная копия репозитория.

GitHub: Создание копии репозитория.

В качестве примера я сделал форк репозитория My_Project пользователя LibreRussia. Теперь в моем аккаунте (mazhartsev) есть его полная копия, с которой я могу спокойно работать не опасаясь покорёжить основной.

Теперь внесем изменения в файл README.md, выбрав его и нажав значок с карандашом.

GitHub: Онлайн редактирование текстовых файлов.

Одна из дополнительных приятных функций GitHub — возможность редактировать текстовые файлы через браузер.

Добавим строку Привет, Мир! и сохраним файл.

GitHub: Онлайн редактирование текстовых файлов.

Теперь предложим наши изменения в основной репозиторий, то есть сделаем Pull Requests.

Pull Requests

Для того, чтобы предложить свои изменения в основной репозиторий, необходимо перейти в раздел Pull Requests и нажать кнопку New pull request.

GitHub: Создание Pull Requests.
GitHub: Создание Pull Requests.

Будет открыта страница, показывающая внесенные изменения. Нажимаем Create pull request.

GitHub: Создание Pull Requests.

Далее будет предложено оставить комментарий к предлагаемым изменениям. Подробно описывать все внесенные изменения не надо, Git сам покажет их.

GitHub: Создание Pull Requests.
GitHub: Создание Pull Requests.

Внесенные изменения отправлены на рассмотрение владельцу основного репозитория, который получит соответствующие уведомления на электронный адрес и в интерфейсе GitHub. Для демонстрации я перейду из своего аккаунта в аккаунт LibreRussia.

Принятие Pull Requests

Уведомление о предложенных изменениях приходят на электронную почту владельца репозитория и отображаются в интерфейсе GitHub.

GitHub: Принятие Pull Requests.
GitHub: Принятие Pull Requests.

Откроем уведомления.

GitHub: Принятие Pull Requests.

Чтобы выполнить слияние (англ. Merge) предложенных изменений нажмите кнопку Merge pull request.

GitHub: Принятие Pull Requests.

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

GitHub: Принятие Pull Requests.

Теперь проверим файл в основном репозитории.

GitHub: Принятие Pull Requests.
GitHub: Принятие Pull Requests.

Как видно, файл успешно изменен и в нём появилась строка, добавленная другим пользователем.

В любой момент можно отменить сделанные изменения и откатиться к предыдущим версиям файла. Все это больше относится к функциям самой системы управления версиями Git.

Подробнее о слияниях смотрите главу Ветвление в Git из официального руководства Pro Git.

Слияние копий репозиториев похоже на слияние двух веток, подробнее смотрите Ветвление.

Статьи на тему Pull Requests:

Ветвление

Внутри одного репозитория можно создавать параллельные ветви (англ. Branch). Ветвление означает, что вы отклоняетесь от основной линии разработки и продолжаете работу, не вмешиваясь в основную линию. В любой момент можно выполнить слияние веток. Подробнее о ветвлении смотрите главу Ветвление в Git из официального руководства Pro Git.

Ветки напоминают функции Копирование репозитория (Fork) и Pull Requests, но при этом всё происходит в рамках одного репозитория.

GitHub: Ветвление.

Данная функция очень полезна при создании документации, так как именно на ней основывается возможность вести одновременно несколько версий руководства (см. Несколько версий документации).

Обход блокировки GitHub

Не так давно случился неприятный инцидент с блокировкой GitHub на территории России. Не буду давать какую-либо оценку данному событию, но на случай повторения ситуации приведу способы обхода блокировки.

Я воспользовался утилитой torsocks, которая устанавливается вместе с Tor. Чтобы установить Tor в Debian/Ubuntu выполните в терминале:

sudo apt-get install tor

Пакет tor включает программу torsocks. Если к команде запуска программы (например, git) приписать torsocks, то её сетевая активность (включая разрешение доменов) пойдёт через Tor. Сетевая активность, которую нельзя пропустить через Tor, будет отсекаться (например, UDP). Данный способ не работает в Windows.

torsocks git push
torsocks git pull

Другие способы обхода смотрите в статьях:

GitHub и совместная работа над документацией

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


Работа с Read The Docs

Read the Docs (https://readthedocs.org) служит для хранения и публикации документации, позволяет легко в ней ориентироваться и делает её доступной для полноценного поиска. Можно импортировать документацию из проекта, используя любую известную систему контроля версий: Mercurial, Git, Subversion и Bazaar.

Read The Docs поддерживает webhooks , так что документация может быть обновлена сразу после добавления в репозиторий нового кода. Также есть поддержка версий, поэтому можно собирать отдельные варианты (в том числе отдельные локализации) документации для тэгов и веток, которые есть в репозитории.

Read the Docs
Read the Docs
Read the Docs

Регистрация

Read the Docs полностью бесплатен, регистрация на нём не занимает много времени.

Read the Docs: Регистрация.

Привязка к GitHub

После регистрации можно привязать свой аккаунт на GitHub или Bitbucket.

Read the Docs: Привязка к GitHub.
Read the Docs: Привязка к GitHub.
Read the Docs: Привязка к GitHub.

Создание проекта

Прежде чем выгрузить свой проект на Read the Docs, его необходимо создать и загрузить на GitHub. Структура репозитория должна содержать папку docs, в которой и будет находиться проект Sphinx (т.е. команду sphinx-quickstart нужно запускать в папке docs).

$ cd /path/to/project
$ mkdir docs
$ cd docs
$ sphinx-quickstart
$ make html

После создания Sphinx-проекта и генерации документации, загружаем репозиторий на GitHub.

Read the Docs: Выгрузка проекта на GitHub.

Импорт проекта

После создания проекта и выгрузки его на GitHub в панели управления Read the Docs нажимаем Import a project.

Read the Docs: Импорт проекта.
Read the Docs: Импорт проекта.

Синхронизируемся с GitHub и выбираем репозиторий, документация из которого будет опубликована на Read the Docs. Нажимаем кнопку Create.

Read the Docs: Импорт проекта.
Read the Docs: Импорт проекта.

Далее будет предложено выбрать Имя проекта (это будет часть URL-адреса документации Имя-проекта.readthedocs.org), Тип репозитория и также можно установить галочку Edit advanced project options для включения расширенных настроек.

Read the Docs: Импорт проекта.

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

Read the Docs: Импорт проекта.

Дальше будет предложено выбрать ещё ряд настроек таких, как версия интерпретатора (я предпочитаю собирать 3-й версией, меньше проблем с кириллицей), ветку репозитория, на основе которой будет сгенерирована версия руководства, а также стандартную версию руководства, на которую будет происходить перенаправление по умолчанию.

Read the Docs: Импорт проекта.

После выбора всех настроек будет произведена первая сборка руководства.

Read the Docs: Импорт проекта.

Так выглядит стандартная тема оформления Read the Docs, при желании можно использовать любую другую (см. Смена HTML-темы):

Read the Docs: Импорт проекта.

Автоматическая публикация

Для включения автоматической публикации документации на Read The Docs при обновлении репозитория GitHub, перейдите в репозиторий проекта на GitHub в раздел Settings.

Read the Docs: Автоматическая сборка.

Выберите пункт Webhooks & Services и добавьте сервис Read the Docs.

Read the Docs: Автоматическая сборка.

Не путайте автоматическую публикацию с автоматической сборкой (генерацией) самой документации Sphinx, об этом подробнее смотрите раздел Автоматическая сборка.

Настройка

В панели управления проектом на Read the Docs в разделе Админ можно изменить настройки проекта, добавить новые версии документации, назначить кураторов и т.д.

Read the Docs: Админка.

Несколько версий документации

Версии документации создаются на основе веток Git-репозитория, подробнее смотрите Ветвление.

Read the Docs: Версии.

Ошибки сборки

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

Read the Docs: Ошибки сборки.

Наиболее часто возникаю ошибки при сборке PDF. При сборке используется генерация в LaTeX. Стандартные настройки шаблона LaTeX, используемого Read the Docs, не поддерживают кириллицу. Подробнее смотрите раздел Ошибки при сборке PDF на Read The Docs.