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

  • Tutorial
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)

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

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

Похожие публикации

Комментарии 3
    0
    Включать Jekyll ради того, чтобы не держать ветку gh-pages?..
      0
      Всё равно здесь оставят эту ссылку, так что зачем тянуть время, сделаю это сразу :)
      Read The Docs
        0
        Скрипт помог, но как понимаю он изменяет текущую папку? Немного доработал его, чтобы он делал git clone во временную папку, а текущую почти не изменял (только брал документацию отсюда).
        github.com/devopshq/teamcity/blob/develop/docs-sphinx/publish-gh-pages.sh

        Только полноправные пользователи могут оставлять комментарии. Войдите, пожалуйста.

        Самое читаемое