Автоматическая генерация документации на php проекте
Часто бывает, что в проекте (особенно если над ним работает больше одного разработчика) разрастается количество кода (классов, функций) И в какой-то момент вы понимаете, что тратите очень много времени на то что, встретив класс, который написали ваши коллеги, вам надо пойти в файловой структуре поискать код класса, посмотреть требуемый метод, понять какие где свойства используются, что это вообще и зачем оно так, а не иначе.
В этой статье я опишу вариант настройки автоматической генерации документации по вашему php коду.
Для этого нам потребуется Composer, phpDocumentor и Git
Код должен быть покрыт PHPDoc комментариями.
Чтобы установить composer, надо следовать инструкциям на официальном сайте
Если лень читать инструкцию, то можно просто сделать:
curl -sS https://getcomposer.org/installer | sudo php -- --install-dir=/usr/local/bin --filename=composer composer -V (если всё хорошо, то композер должен показать свою версию)
Инструкция по установке phpDocumentor на официальном сайте
Если лень читать:
composer require "phpdocumentor/phpdocumentor:2.*"
Еще надо установить graphviz
sudo apt-get install graphvizчтобы phpDocumentor мог нарисовать красивые диаграммы наследования классов
Теперь, чтобы сгенерить документацию, вам надо указать путь до документора, путь до кода, по которому будет строиться документация, и место, куда документацию класть.
Примерно так:
php /var/www/vendor/bin/phpdoc -d /var/www/project/classes -t /var/www/documentation/ --template="clean"
Если вы построили документацию, а надо перестроить ее еще раз, то просто очистите папку
rm -rf /var/www/documentation/*
Теперь если ваш проект под гитом - вам нужно настроить гитхук post-merge, который будет вам перегенеривать документацию, если вы подтянули изменения от ваших коллег и изменения оказались в файлах, по которым строится документация.
#!/bin/bash DOC_PATH="/var/www/documentation" CLASSES_PATH="/var/www/project/classes" DOCUMENTOR_PATH="/var/www/vendor/bin/phpdoc" RELATIVE_CLASSES_PATH="classes" in_classes=`(grep "$RELATIVE_CLASSES_PATH" <<< "$files")` if [ "$in_classes" != "" ]; then rm -rf "$DOC_PATH"/* php "$DOCUMENTOR_PATH" -d "$CLASSES_PATH" -t "$DOC_PATH" --template="clean" fi
Если проект не под гитом, вы можете придумать какую-то альтернативу. Например по крону периодически перегенеривать её.
{{ 'Comments (%count%)' | trans {count:count} }}
{{ 'Comments are closed.' | trans }}