Как писать техническую документацию к проекту?

Это статья — личный опыт. Сильно много расписывать не буду. Пишу ее больше для того, чтобы самому не забыть о том что сделал ).

Ну и думаю кому то этот опыт может быть полезен.

Что мы получим в итоге.

Сейчас есть документация реализованная на сайте https://cms.skeeks.com/docs 

В результате получим:

https://cms.skeeks.com/cms-docs/ru/overview.html

https://cms.skeeks.com/cms-docs/en/overview.html

https://docs.cms.skeeks.com

https://media.readthedocs.org/pdf/skeeks-cms/latest/skeeks-cms.pdf - pdf документация сгенерированная сервисом read the docs.

Предисловие.

Есть наша SkeekS CMS, а вот документации по ней нет. Как писать документацию? Самое первое что сделано, так это документация на самом сайте, реализованная средствами самой же cms. 

https://cms.skeeks.com/docs.

В целом неплохо, писать удобно. Благодаря cms есть пара языков, если надо можно и больше. И на первых порах она вполне себе выручает. Однако, не все так хорошо.

Чего не хватает?

• Как минимум версионирования
• Скачать ее офлайн
• Распечатать в каком либо формате
• Сделать pdf
• Совместная доработка и обновление

Вижу два решения этих проблем. Допрограммировать сайт или поискать какие то готовые решения. Ведь в современном мире много разных проектов и еще больше документации к ним.

Решение.

Погуглив, можно найти много разных решений. И я остановился на одном из них.

Sphinx — Python documentation generator (http://www.sphinx-doc.org/)

Многие знакомые мне, крупные проекты используют именно этот метод написания документации.

Не так давно статья на хабре о том, что ядро linux документируют таким же образом https://habrahabr.ru/post/316758/

https://github.com/skeeks-cms/cms/tree/master/docs — проект документации SkeekS CMS (который и был реализован)

https://docs.readthedocs.io/en/latest/ — документация по сервису Read the docs

http://sphinx-ru.readthedocs.io/ru/latest/rst-markup.html — стандартный синтаксис разметки reStructuredText

Процесс.

На сервере линукс, с установленным python в консоле делаем команды.

apt-get install python-pip

 

pip install Sphinx
# У нас будет много переводов
pip install sphinx-intl
# Документация должна быть красивой
pip install sphinx_rtd_theme

 

Полезные команды с которыми я столкнулся и использую в работе

make gettext
make html
sphinx-intl update -p _build/gettext -l ru

sphinx-build -D language='ru' ./ build/ru
sphinx-build ./ build/en