Разработка этой документации ведётся с помощью системы документирования Sphinx, которую используют многие другие open-source проекты.
Для сборки документации из исходников (получение красивой html-версии) необходимо установить сам Sphinx, sphinx-autobuild (для авто-обновления сборки) и тему оформления. Если коротко, то нужно в консоли вызвать следующие команды:
sudo pip install Sphinx
sudo pip install sphinx-autobuild
sudo pip install guzzle_sphinx_theme
Проект документации лежит в папке docs проекта lc-front. Развернуть его локально и получить готовую сборку
очень просто:
cd path/to/libicraft/lc-front/docs
sphinx-build -a . _build/ && sphinx-autobuild . _build/
После этого можно открыть в браузере http://127.0.0.1:8000/ и увидеть результат. Страница будет автоматически обновляться при изменении исходников.
Если нужна просто одноразовая сборка, можно воспользоваться упрощённым способом — находясь в папке проекта, запустить команду:
make html
Для редактирования исходников можно использовать любой текстовый редактор, но будет удобнее, если он поддерживает подсветку синтаксиса для файлов reST.
Фиксация изменений производится так же, как и для любого исходника в git-репозитории.
В процессе написания документации удобно использовать sphinx-autobuild — инструмент, который “слушает” изменения в исходниках
документации, автоматически пересобирает проект, раздаёт его через свой локальный веб-сервер и автоматически
перезагружает открытую в браузере страницу после каждой пересборки. Таким образом, не нужно каждый раз жать F5
после изменений, чтобы посмотреть результат.
sphinx-autobuild -i ".git/*" -i ".idea/*" . _build/
Для запуска используется опция -i для того, чтобы утилита не учитывала изменения в файлах IDE и репозитории git.
Предупреждение
При изменениях в файлах темы (например, в style.css) sphinx-autobuild не всегда срабатывает корректно. В
таких случаях, чтобы увидеть результат изменений, следует полностью пересобрать проект. Помогает следующая команда:
sphinx-build -a . _build/ && sphinx-autobuild -i ".git/*" -i ".idea/*" . _build/
Основная идея работы со Sphinx — редактировать простые текстовые файлы со специальной разметкой, которая определяет форматирование, структуру и взаимосвязи разных кусков документации, а затем запустить сборщик, который из этих файлов сгенерирует красивый html, pdf или другой поддерживаемый формат по желанию.
Формат исходных файлов называется reStructuredText (расширение файлов .rst). Чтобы его изучить, полезно почитать
следующее:
В корневой папке проекта присутствуют только два исходных файла документации:
index.rst.contents.rst, которое определяет структуру всей документации.Документация делится на разделы, исходные файлы каждого из которых лежат в отдельной папке. В папке раздела должен
быть создан файл index.rst с оглавлением (директивой toctree), в котором перечислены все файлы с контентом из
этого раздела и индексные файлы додразделов (если есть). Ссылка на файл index.rst раздела добавляется в toctree
главного оглавления проекта в файле contents.rst.
Подробнее об организации структуры с помощью директивы toctree можно почитать в соответствующем разделе
документации Sphinx.
.rst¶Максимальная ширина строки в исходном файле - 120 символов. Всё, что длиннее, должно переноситься.
index.rst используем #### сверху и снизу..rst с контентом форматируем с ***** сверху и снизу.===============---------------^^^^^^^^^^^^^^^"""""""""""""""Если идёт текст, а дальше заголовок, то ставим перед ним две пробельные строки. Если заголовок, а затем сразу заголовок следующего уровня, то одну пробельную строку.
1 2 3 4 5 6 7 | #######################
Заголовок раздела/папки
#######################
.. toctree::
bla-bla
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 | ***************
Заголовок файла
***************
Первый уровень внутри файла
===========================
Текст
Второй уровень
--------------
Третий
^^^^^^
Текст
Четвёртый
"""""""""
Текст
|
В качестве основы для внешнего вида используется тема Sphinx guzzle_sphinx_theme с некоторыми исправлениями. Для доработки темы в папке _themes
создана новая тема под названием libicraft, которая унаследована от guzzle (это прописано в файле
_themes/libicraft/theme.conf). В файле _themes/libicraft/static/style.css прописаны
некоторые исправления адаптивной вёрстки и улучшения внешнего вида (шрифтов) темы. Есть доработки и в html-шаблонах
темы, которые лежат в папке _themes/libicraft. Состав боковой панели для разных типов страниц настоен с помощью
конфигурационной переменной html_sidebars в файле conf.py.
Возможности кастомизации внешнего вида документации в Sphinx довольно широки. Об этом можно почитать тут:
Альтернативные темы Sphinx, на которые стоит обратить внимание:
В процессе доработки темы оформления обнаружились полезные ресурсы на тему того, где и как брать красивые шрифты для текста:
Google Fonts — большая бесплатная коллекция шрифтов от Google. Шрифты из этой библиотеки легко подключать в css-файле:
@import url("http://fonts.googleapis.com/css?family=Roboto+Condensed");
Fontspace — можно найти и скачать бесплатные шрифты. Использовать скачанный шрифт чуть сложнее:
@font-face {
font-family: 'Ubuntu Mono';
src: url('fonts/ubuntu-mono/UbuntuMono-R.ttf');
}
Обсуждение на stackexchange о том, какие шрифты лучше подходят для технической документации