Автоматическая генерация документации на 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

Если проект не под гитом, вы можете придумать какую-то альтернативу. Например по крону периодически перегенеривать её.