Главная

Sphinx-документация на GitHub Pages

2013-05-19 в 23:37, admin, рубрики: Git, github, github.io, sphinx, метки: github, github.io, sphinx

GitHub Pages — это такая классная шизофреническая штука, которая может а)показывать созданную при помощи встроенного редактора страничку, б)генерировать Jekyll-блог и в)отображать html-файлы на произвольном домене.
В последнем образе она нас и интересует для размещения документации, написанной с использованием Sphinx.

Технически, в любом случае создаётся ветка gh-pages (за исключением), из которой отображается контент.
Итак, проект — это один репозиторий, документация к нему — другой, нет смысла смешивать их.
В master репозитория документации у нас хранятся исходники в формате ReStructuredText и конфигурационные файлы вместе с историей изменений. В gh-pages мало того, что история лишена смысла, так ещё и логически эта ветка существует параллельно master. Из таких предпосылок я исходил, создавая следующий скрипт.

#!/bin/sh
shopt -s extglob dotglob

CURR_DIR="$(pwd)"
TMP_DIR="$CURR_DIR"-gh-pages

sh build.sh

rm -rf "$TMP_DIR"
cp -r . "$TMP_DIR"
cd "$TMP_DIR"

git branch -D gh-pages
git checkout --orphan gh-pages
rm -rf !(.git|.gitignore)

cp -r "$CURR_DIR"/_build/html/* .
touch .nojekyll
echo "droidparts.org" > CNAME

git add -A
git commit -m "published"
git push origin :gh-pages
git push origin gh-pages

rm -rf "$TMP_DIR"

(link)

Последовательность действий:

Запускаем скрипт, собирающий документацию.
Копируем репозиторий во временную папку, переходим в неё.
Удаляем gh-pages, создаём её снова. Параметр --orphan отвечает за то, что ветка будет создана без родительского комита. Т.е. без привязки к master, что и требовалось. Также очищаем папку.
Копируем сгенерированные на первом шаге файлы.
Добавляем .nojekyll, чтобы GitHub Pages не подпускал Jekyll к папкам с нижним подчёркиванием.
Создаём файл CNAME с доменом, с которого всё будет отдаваться. Естественно, также нужно настроить DNS.
Наконец, комитим, удаляем gh-pages с сервера, делаем push.

В качестве бонуса наблюдаем баг, когда GitHub сообщает о количестве комитов ahead & behind, а при попытке сравнить сообщает, что .... Или так и должно быть?

Автор: yanchenko

Источник