Пользователь
0,0
рейтинг
3 октября 2012 в 00:31

Разработка → Делаем учебник или документацию за час на Сфинксе

Я веду курс веб-программирования. Когда учишь людей, поговорка «сапожник без сапог» к тебе относиться не должна: ты должен делать всё без видимых усилий и быстро. Учебник должен делаться легко и просто, и выглядеть хорошо.

В общем, если вам нужно сделать документацию, учебник или просто набор текстов с иллюстрациями, то вам нужен Python Sphinx, и здесь я расскажу, как быстро его настроить и использовать.

Пустая страница новой документации


Устанавливаем Питон и инструменты


На платформе Windows вам понадобится Питон, и его установку я оставляю вам в качестве домашнего задания. Кроме Питона нужен пакет distribute и curl (или wget). Скачиваем и устанавливаем distribute и pip:

    curl http://python-distribute.org/distribute_setup.py | python
    curl https://raw.github.com/pypa/pip/master/contrib/get-pip.py | python


Теперь можно установить сам Sphinx:

    pip install sphinx


* в Ubuntu/Debian добавьте sudo

Создаём проект учебника


После этого достаточно создать папку для проекта и в ней запустить скрипт sphinx-quickstart. Он задаст несколько вопросов. Из них, на мой взгяд, по-другому надо ответить на два:

    > Separate source and build directories (y/N) [n]: y (Сделать ли раздельные папки исходников и готовых страниц - Да)
    > Create Windows command file? (Y/n) [y]: n (Сделать ли файл .bat, - нет, если у вас Linux)


Заготовка проекта готова. Дальше можно открывать index.rst и пробовать править.

Как изучить разметку ReStructured Text? Хороший софт не требует чтения документации. Сфинкс — не исключение: на всех сделанных им страницах есть ссылка «Показать исходный код» («Show source»). Подглядывая в чужие исходники, можно научиться очень многому и быстро. Смотрите и экспериментируйте.

Написав что-нибудь существенное, запускаем сборку HTML в консоли:

    make html


Открываем из папки _build/html страницу index.html, и радуемся. У нас готов статический сайт с поиском (на JavaScript).

Страница на Сфинксе в стандартном стиле

Автосборка


Наконец, когда мы стали редактировать файлы, оказывается, что каждый раз запускать make html и обновлять броузер — очень нудное занятие. Пакет inotify позволяет следить за изменениями файлов и запускать команды. Устанавливаем infotify-tools и xdotool:

	sudo apt-get install inotify-tools xdotool


Простейший вариант скрипта, следящего за обновлениями. Он запускает сборку многостраничной документации html и единого файла, после чего нажимает в Хроме в открытой вкладке кнопку F5:

	inotifywait -mr source --exclude _build -e close_write -e create -e delete -e move | while read file event; do
		make singlehtml html
		xdotool search --name Chromium key --window %@ F5
	done


Но быстро выясняется недостаток: сколько файлов обновилось, столько раз и сборка запускается. Нужно группировать близкие по времени события в одно. Поискав разные варианты, я решил не писать свой скрипт на Питоне, а обойтись шелл-скриптом, запускаемым из папки проекта:

	inotifywait -mr source --exclude _build -e close_write -e create -e delete -e move --format '%w %e %T' --timefmt '%H%M%S' | while read file event tm; do
		current=$(date +'%H%M%S')
		delta=`expr $current - $tm`
		if [ $delta -lt 2 -a $delta -gt -2 ] ; then
			sleep 1  # спать 1 секунду на случай если не все файлы скопированы
			make html singlehtml
			xdotool search --name Chromium key --window %@ F5
		fi
	done


Он сравнивает время события со временем, когда до него дошла очередь. Если событие произошло 1-2 секунды назад, значит надо собрать документацию заново. Чтобы другие системы доделали своё дело (например закончился hg update), скрипт спит 1 секунду. Начинается сборка. После этого обрабатываются следующие события, и они будут уже очень старыми, поэтому скрипт их сразу пропускает.

Вы также можете встроить его в Makefile:

	.PHONY autobuild
	autobuild:
		<скрипт>


Форматы документации


Сфинкс умеет делать многостраничный HTML, умеет сделать единый файл, а также PDF, электронные книги (EPUB) и кто-то делал CHM.

Сделать PDF есть 2 способа: установить Latex, выкачав 1 ГБ пакетов, зато на выходе будет кофетка. Другой вариант — новый питоновский пакет rst2pdf, быстрый и простой, выдаст PDF очень простецкого вида. Над ним придётся потрудиться, чтобы довести стиль до приличного.

Скачивание документации в PDF


Я добавляю ссылку на скачивание PDF на главной странице, это инструкция download. Чтобы она не была видна в самóм PDF, есть блок only:

    .. only:: html
        Этот учебник можно скачать :download:`в формате PDF <../build/latex/manual.pdf>`.


Внимание: когда Сфинкс собирает HTML, он скопирует этот файл в папку статики. Поэтому чтобы версии совпадали, надо генерировать сначала PDF, только потом HTML.

Публикация


Есть 3 варианта. Простейший — залить проект на BitBucket, добавить к репозиторию бесплатный сервис Read The Docs, затем зарегистрироваться на ReadTheDocs и создать там проект. Когда вы будете заливать новые ревизии в главной ветке, RTD будет скачивать их и переделывать документацию. Таким образом, документацией для программной библиотеки специально заниматься не нужно: достаточно поддерживать в актуальном состоянии докстринги.

Если же хочется держать закрытый сайт для своих, можно сделать простой запароленный сайт и собирать его вручную. В корень сайта достаточно закачать содержимое папки _build/html. Я для этого использую rsync и написал 2 строки в Makefile:

.PHONY: sync
sync: latexpdf html
	rsync -ave ssh build/html/ siberiano@hosting:/home/siberiano/webapps/course_manual/ --delete


Сначала будет собрана документация в формате latexpdf, затем в html (и в «download» будет добавлена PDF), затем rsync залёт файлы на хостинг, удалив старые (опция --delete).

Если нужна своя закрытая система, не зависящая от чужих, можно запустить у себя клон ReadTheDocs.

Красивое оформление


Сфинкс использует «темы», это шаблоны Jinja плюс статические файлы, сложенные в одну папку. Я выложил несколько собранных из свободного доступа тем. Чтобы включить тему, нужно настроить 2 строки conf.py:

html_theme = 'armstrong'  # имя темы
html_theme_path = ['themes']  # папка внутри source, где лежат папки тем


Результат:

Документация с темой Armstrong

Резюме


Логотип проекта
Сфинкс — очень мощный инструмент, который может сделать вам статический сайт из минимума данных. Для большого количества статического текста и фотографий это самый лучший вариант. Его можно быстро поднять и очень быстро обновлять. А документация для программных библиотек будет вообще собираться сама без ваших усилий — просто мечта разработчика!

P.S. Я забыл добавить примеры, как сделать автоматическую документацию. На самом деле настройки и исходный код можно подглядеть в любом проекте, а также полезно знать sphinx-apidoc.

Добавление от 11.10.12: на ГитХабе я нашёл редактор преформатированных таблиц для SublimeText, сделанный специально для тех, кто редактирует RST и Markdown.
@siberiano
карма
93,7
рейтинг 0,0
Реклама помогает поддерживать и развивать наши сервисы

Подробнее
Реклама

Самое читаемое Разработка

Комментарии (6)

  • +1
    Спасибо за наводку на inotifywait.
    Про существование библиотеки знал, а вот про существование консольной утилиты нет.
  • 0
    PDF очень советую делать через latex.
    В своё время я так скомпилировал документацию по Django 1.0 и распечатал.
    Получилась очень приятная бумажная книжка почти на 500 листов.

    Если б не Sphinx, вряд ли бы я решился с монитора читать документацию от корки до корки.
  • 0
    Сравнительно активно использую Sphinx (+autodoc) для изучения чужих библиотек — удобно :)

    вопрос к знающим людям: как можно заставить autodoc отключить режим «respect __all__»? Полтора дня (потом плюнул — устал ;) ) изучения сорцов дали знание, что есть некий параметр при вызовах парсеров, но так и не смог найти где его поменять без «пересборки» Sphinx-а :(
  • 0
    Жалко, что не рассказали о недостатках. Например, таблицы в RST очень трудоемко оформлять, особенно редактировать.
    • 0
      Я хотел просто сделать ознакомительную статью, чтобы показать возможности. Сложностей много, конечно, например, русификация и собственные шаблоны. Но это на порядки проще и надёжнее, чем ставить CMS, и на порядки проще, чем делать всё вручную.
    • 0
      Добавил в конец текста: редактор преформатированных таблиц для SublimeText
      github.com/vkocubinsky/SublimeTableEditor

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