Посты с тэгом restructuredtext

Документация python проекта на практике

Документации в python проектах пишется при помощи sphinx, он умеет с помошью расширения automodule читать докстринги и формировать документацию из кода.

Создать проект можно ответив на вопросы через sphinx-quickstart или использовать уже подготовленный шаблон который генерит дополнительно API для пакета:

sphinx-apidoc -F -o docs sacrud

Creating file docs/sacrud_deform.rst.
Creating file docs/sacrud_deform.tests.rst.
Creating file docs/conf.py.
Creating file docs/index.rst.
Creating file docs/Makefile.
Creating file docs/make.bat.

Автогенератор API обычно создает много лишнего и далеко не идеально генерит названия, поэтому удалим API тестов и попереимеуем все остальное.

Для сборки доков нужно

Хостим документацию 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

Посты с тэгом restructuredtext

Документация python проекта на практике

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

Обновления

Раздел «Блоги»

Тэги