testomat.io управление авто тестамиСейчас у меня есть задача создания документации к существующему фреймворку автоматизации, который написан на python. Для того чтобы документация была живая и поддерживаемая, она должна быть чем поближе к коду. Поближе к коду? Лежать вместе с кодом под одним версионым контролем, полностью или частично генерироваться с исходников и т.д.
Я выбрал http://sphinx-doc.org мега удобный инструмент, который позволяет мне сделать быструю и красивую документацию. Сам сфинкс описывать не буду, но вот хочу поделиться с вами инструментарием, который позволит быстро создавать нужный контент в нужном формате.
Сфинкс использует
reStructuredTextсинтаксис для того чтобы создавать документацию. Потом с reStructuredText можно сделать иhtmlиepubи т.д.
Для того чтобы создавать reStructuredText я использую мой любимый SublimeText. Редактор имеет сразу встроенные возможности создавать и подсвечивать нужные файлы, но этот процесс можно немного упростить за счет установки дополнительных плагинов.
- RestructuredText Improved - Packages - Package Control улучшает во многом подсветку нужных элементов
-
GitHub - mgaitan/sublime-rst-completion: Restructured Text snippets and code completion hotkeys for Sublime Text 2 and 3 добавляет очень удобный автокомплит и навигацию по
rstфайлам.
После всех установок rst файлы будут выглядеть вот так вот:
По второму плагину даже есть видео:
Также sublime-rst-completion добавляет возможность делать preview html или другого формата выходных данных.
Ну и последнее, в моей небольшой заметке, если Вы описываете rst файлы, то нужно их компилировать в html. И этот процесс можно также автоматизировать через функции build в sublime. Т.е. компилировать выходные файлы не выходя из самого редактора.
Для этого нужно сделать несколько действий в sublime:
- Tools → Build System → New Build System
- Создаем конфигурацию запуска, более детально можно посмотреть здесь http://sublimetext.info/docs/en/reference/build_systems.html
{
"working_dir": "${folder}\\docs",
"cmd": "make.bat clean & make.bat html"
}
- и по Ctrl+B все ваши
rstфайлы будут компилироваться в нужный вам формат.
А дальше нужно только просмотреть, чтобы текст красиво смотрелся.
В результате получаем вот такую вот документацию с возможностью поиска, привязке к коду, автоматической подсветкой кода, генерации индекса классов и методов и т.д.:
А как Вы документируете Вашу автоматизацию? И какие процессы и \ или инструменты используете?
