Готовим документацию в Sphinx: рецепты и мой опыт
-
-
40 мин
Доклад — поваренная книга, в которой я расскажу рецепты внедрения Sphinx. Sphinx — генератор документации, который преобразует текст, написанный на языках разметки reStructuredText и Markdown, в различные форматы: HTML, PDF, DOCX и другие.
Именно Sphinx стал основным инструментом технического писателя в нашей компании. Внедрение Sphinx позволило нам одновременно использовать преимущества концепции Docs-As-Code и мощные фичи, так привычные мне по работе с Help&Manual.
В своем докладе я расскажу:
- какую документацию мы хотели приготовить: как Sphinx закрыл наши требования к выходным форматам документации;
- с какими проблемами мы столкнулись: нам требовалась поддержка единого источника и локализация. У нашего продукта есть Cloud и Enterprise-версии, которые отличаются по своим функциональным возможностям, а также интерфейс на русском и английском языках;
- как в итоге состряпали полезную документацию: изменения процессов в команде разработки и итоговые результаты работы.