- PVSM.RU - https://www.pvsm.ru -
GitHub Pages — это такая классная шизофреническая штука, которая может а)показывать созданную при помощи встроенного редактора страничку, б)генерировать Jekyll-блог и в)отображать html-файлы на произвольном домене.
В последнем образе она нас и интересует для размещения документации, написанной с использованием Sphinx [1].
Технически, в любом случае создаётся ветка gh-pages
(за исключением [2]), из которой отображается контент.
Итак, проект — это один репозиторий, документация к нему — другой, нет смысла смешивать их.
В 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 [3])
Последовательность действий:
gh-pages
, создаём её снова. Параметр --orphan
отвечает за то, что ветка будет создана без родительского комита. Т.е. без привязки к master
, что и требовалось. Также очищаем папку..nojekyll
, чтобы GitHub Pages не подпускал Jekyll к папкам с нижним подчёркиванием.CNAME
с доменом, с которого всё будет отдаваться. Естественно, также нужно настроить DNS [4].gh-pages
с сервера, делаем push.В качестве бонуса наблюдаем баг, когда GitHub сообщает о количестве комитов ahead & behind [5], а при попытке сравнить сообщает, что ... [6]. Или так и должно быть?
Автор: yanchenko
Источник [7]
Сайт-источник PVSM.RU: https://www.pvsm.ru
Путь до страницы источника: https://www.pvsm.ru/git/34674
Ссылки в тексте:
[1] Sphinx: http://sphinx-doc.org
[2] исключением: https://help.github.com/articles/creating-pages-with-the-automatic-generator
[3] link: https://github.com/yanchenko/droidparts.org/blob/master/publish.sh
[4] настроить DNS: https://help.github.com/articles/setting-up-a-custom-domain-with-pages
[5] ahead & behind: https://github.com/yanchenko/droidparts.org/branches
[6] ...: https://github.com/yanchenko/droidparts.org/compare/master...gh-pages
[7] Источник: http://habrahabr.ru/post/180213/
Нажмите здесь для печати.