Хостим документацию Sphinx на github¶

Немного допиленная версия этого http://djangonaut.blogspot.com/2009/05/sphinx-documentation-github-pages-3.html

По порядку:

• создать репозитарий на github
• добавить туда свой локальный репозитарий с проектом Sphinx
• захостить репозитарий через сервис Pages
• поправить Makefile в Sphinx проекте

docs_dir = doc
ghdocs:
 rm -rf $(docs_dir)
 $(MAKE) clean
 $(MAKE) html
 cp -r build/html $(docs_dir)
 mv $(docs_dir)/_static $(docs_dir)/static
 mv $(docs_dir)/_sources $(docs_dir)/sources
 perl -pi -e "s/_sources/sources/g;" $(docs_dir)/*.html
 perl -pi -e "s/_static/static/g;" $(docs_dir)/*.html
 git add .
 git commit -a -m "Updates $(project)."
 git checkout gh-pages
 cp -rf $(docs_dir)/* .
 git add .
 git commit -a -m 'Updates $(project) documentation.'
 git checkout master
 rm -rf $(docs_dir)
 git push origin gh-pages

Теперь при запуске make ghdocs будет автоматом генерироваться новая документация и пушаться на github.

Пример здесь http://uralbash.github.com/python-web-lectures/

Для автоматической замены директорий _static и _sources, можно установить модуль sphinxtogithub.

$ pip install sphinxtogithub

И добавить в проекте в config.py:

extensions = ["sphinxtogithub", ]

В этом случае нужно закомментировать в скрипте строчки:

mv $(docs_dir)/_static $(docs_dir)/static

и

mv $(docs_dir)/_sources $(docs_dir)/sources

Это необходимо делать потому-что github не понимает директории начинающиеся с подчеркивания.