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


Документация Linux ядра переходит на Python Sphinx

Linux ядро на сегодняшний день — самый динамичный, сложный, крупный проект с открытым кодом. Как же обстоят дела с его документацией? Существует прямая связь: чем качественнее и доступнее документация проекта, тем проще для посторонних изучить основы дела, освоиться и стать полноправным участником.





На семинаре Kernel Recipies мейнтейнер документации Linux ядра Jonathan Corbet рассказал о нынешнем положении дел с документацией и о том, как будет совершаться переход от анархии к порядку. Первые успехи в этом начинании уже есть. Некоторые документы были недавно конвертированы в 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 в django 1.6 admin

Задача: реализовать полнотекстовый поиск в админке django.
Пример модели, по которой будем делать поиск:

class Movie(models.Model):
    title_en = models.CharField(max_length=255, null=True)
    title_ru = models.CharField(max_length=255, null=True)
    year = models.PositiveSmallIntegerField(null=True)

Читать дальше →


[Из песочницы] Как подружить Django и Sphinx?

Предыстория


Понадобилось мне добавить на сайт функцию поиска. Первой мыслью было — воспользоваться возможностями SQL-сервера, — но искать надо сразу по нескольким таблицам, слова и фразы, да ещё и со стеммингом. Понял, что изобретать свой велосипед будет накладно.

Решил поискать, а что же всё-таки есть из готовых решений? Оказалось, прямо скажем, не густо: django-haystack и django-sphinx. Ранее достоинства и недостатки обоих уже перечисляли, поэтому не буду повторяться.

Потратив какое-то время на чтение блогов и форумов, решил всё-таки попробовать django-sphinx, т. к. в django-haystack, насколько мне известно, с поддержкой Sphinx до сих пор не очень.

Автор же django-sphinx давно забросил свой проект, но есть множество форков, и, говорят, что пользоваться им вполне воз


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


Sphinx documentation + GitHub pages = <3

Вообщем буду краток ;)

Для документирования питоньих проектов очень удобно использовать Sphinx. Это всем известно. А если не известно, то и Python, и Django документированы именно им.

На GitHub'е есть возможность размещения HTML страниц проекта и последующего доступа к ним по адресу: http://username.github.com/repo_name/.

Само собой разумеется, было бы очень неплохо подружить их. И посему я на коленке написал следующую Makefile-команду:

project=YOUR_PROJECT_NAME
docs_dir=$(TMPDIR)/$(project)-docs

ghdocs:
    rm -rf $(docs_dir)
    $(MAKE) -C docs html
    cp -r docs/_build/html $(docs_dir)
    mv $(docs_dir)/_static $(docs_dir)/static
    mv $(docs_dir)/_sources $(docs_dir)/sources
    perl -pi -e "s/_sources/sources


Система развертывания (deploy system)

Как я и обещал в предыдущей серии, посвящаю этот пост нашей системе развертывания.

Система самописная, достаточно тесно связана с процессом разработки и реализована при помощи sh-скрипта.

Общая схема

На рисунке приведена немного сумбурная схема процесса развертывания.

Разработка ведется с использованием SVN установленным на локальном сервере, там же расположен и локальный сервер MySQL. MySQL используется всеми при разработке, структура создается через initdb. Начальные данные в обязательном порядке (