Люблю я всякі автоматизації процесів, ось дійшла черга і до генерації документації у проекті Bluz

Постановка задачі

Виникла необхідність генерувати і публікувати документацію до проекту Bluz, який розміщений на GitHub, в автоматичному режимі, бо “ручками” се робити вже не з руки.

GitHub

В якості хостингу документації будемо використовувати потужності самого GitHub’а, зокрема – GitHub Pages, так що перше що потрібно зробити – створити репозиторій виду bluzphp/bluzphp.github.io, де bluzphp – назва організації (а може бути іменем користувача).

Travis

Дана стаття призначена для тих, хто вже знайомий з Travis CI, але до генерації і автоматичної публікації “руки не дійшли”, так що керівництво для початківців вам треба буде пошукати на іншому ресурсі, хоча в подальшому може з’явитися і тут 😉
Якщо ж з англійським ви дружні, то краще ніж офіційне керівництво важко буде щось знайти.

TravisCI вже використовувався в проекті, так що справа за малим – генерувати документацію, і заливати її в репозиторій на GitHub.

Для генерації документації будемо використовувати PHPDocumentor, додати його в збірку можна двома способами – використовуючи composer дозволяє контролювати версію, але з залежностями можуть виникнути проблеми, так і повільно це – для даного варіанту необхідно додати в composer.json таку залежність:

{
“require-dev”: {
“phpdocumentor/phpdocumentor”: “2.*”
}
}

як альтернатива – скачувати phar-архів:

wget http://phpdoc.org/phpDocumentor.phar

Потім вносимо зміни в файл .travis.yml, це буде виглядати наступним чином (якщо установка була через composer):

before_script:
– mkdir docs
after_script:
– php vendor/bin/phpdoc -d ./src -t ./docs

або так (якщо використовувався phar архів):

before_script:
– mkdir docs
after_script:
– wget http://phpdoc.org/phpDocumentor.phar
– php phpDocumentor.phar -d ./src -t ./docs

Каталог docs можна створити “на льоту” як в даному прикладі, або створити її самому репозиторії як це зроблено в моєму проекті

PHPDocumentor

Після запуску білду в папці docs буде створено статичний сайт, який буде виглядати якось так шаблон clean):

Для більш тонкої настройки можна використовувати конфігураційний файл phpdoc.xml наведу приклад моєї конфігурації з поясненнями:

Bluz
phpdoc
utf8
TODO
FIXME
php
phtml
Bluz
docs
src

GitHub

Так, документація є, тепер її необхідно залити в репозиторій bluzphp/bluzphp.github.io. Для цього нам потрібно створити Access Token в своєму профілі на GitHub:

Скопіюйте його і нікому не показуйте, якщо є сумніви, що хтось зазіхнув на нього – перегенируйте токен заново.

Travis

Повертаємося до Travis – тепер нам потрібно встановити консольний додаток travis, і з його допомогою ми можна закодувати наш токен, щоб ніхто його не зміг підглянути в нашому конфігураційному файлі:

gem install travis
travis encrypt GITHUB_TOKEN=secretvalue -r bluzphp/framework

Отриманий таким чином ключ необхідно додати в ваш конфігураційний файл travis.yml:

env:
global:
– secure: “encryptedsecretvalue”

Детальніше розібратися в що відбувається тут магії вам допоможе офіційна документація щодо шифрування ключів і змінних оточення

Якщо раптом ви не можете зрозуміти, чому не встановлюються глобально ваші зашифровані змінні, то поясню для таких же неуважних як і я – ця фіча не працює для pull-запитів з форков

Йдемо далі – тепер необхідно з використанням даного ключа оновити наш репозиторій. Для зручності подальших маніпуляцій із документацією було створено окремий bash скрипт .travis.sh, а в .travis.yml залишено лише його запуск:

after_script:
– bash .travis.sh

В bash скрипті:

# завантажуємо phpDocumentor
wget http://phpdoc.org/phpDocumentor.phar
# і запускаємо його в “тихому” режимі
# за замовчуванням, він підхопить конфігураційний файл з кореня проекту
php phpDocumentor.phar –quiet
# перенесемо документацію в домашню директорію
cp -R docs $HOME/docs-latest
cd $HOME
# налаштовуємо git
git config –global user.email “[email protected]
git config –global user.name “travis-ci”
git config –global push.default simple
# клонируем репозиторій сторінок
# ось тут ми і будемо використовувати наш шифрований токен
git clone –quiet https://${GITHUB_TOKEN}@github.com/bluzphp/bluzphp.github.io > /dev/null
cd bluzphp.github.io
# очищаємо
git rm -rf ./ > /dev/null
# переносимо документацію
cp -Rf $HOME/docs-latest/* ./
# додаємо всі файли в репозиторій
git add -f .
# коміт
git commit -m “PHPDocumentor (Travis Build: [email protected]$TRAVIS_TAG)”
# пуш
git push -fq origin > /dev/null

Тепер трохи обмежимо білди для яких буде оновлюватися документація наступним умовою:

if [ “$TRAVIS_REPO_SLUG” == “bluzphp/framework” ] && [ “$TRAVIS_PULL_REQUEST” == “false” ] && [ “$TRAVIS_PHP_VERSION” == “7.0” ]; then
# все що вище буде тут
# …
fi

Повний список змінних оточення на Travis є в документації – Default Environment Variables

Все готово – запускаємо білд і дивимося на те, що вийшло… і ось тут мене PHPDocumentor розчарував, не знає він нічого про функції зі змінним числом аргументів (хоча, якщо бути прискіпливим, то проблема все ж у версії бібліотеки PHP-Парсер), помилки незрозумілі показував, ну і лаявся сильно, так що я пішов за альтернативами, хоча варіант робочий, і гріх було про нього не розповісти.

PHPDox

Альтернатива знайшлася відразу – PHPDox, завантажуємо і поїхали – почнемо все з конфігурації за замовчуванням:

# завантажуємо архів phar
wget http://phpdox.de/releases/phpdox.phar
# генеруємо шаблонний конфіг
php phpdox.phar –skel > phpdox.xml

Отриманий таким чином файл був доданий в репозиторій проекту з дрібними правками. Для міграції CI на PHPDox знадобилося лише злегка виправити .travis.sh:

# було
wget http://phpdoc.org/phpDocumentor.phar
php phpDocumentor.phar –quiet
# стало
wget http://phpdox.de/releases/phpdox.phar
php phpdox.phar

Результат вийшов цілком прийнятний, але PHPDox вміє більше – у нього є підтримка PHPUnit, PHPCS, PHPMD, PHPLoc і Git’a, так що я вирішив “прокачати” систему по повній.

З помічених недоліків – проблема з форматуванням прикладів коду записаного в doc-блоках

Git

Почну з найпростішого – для додавання підтримки Git’a досить додати відповідний розділ в phpdox.xml:

В результаті даної маніпуляції в документації з’явиться можливість переглядати історію змін на основі коментарів до комитам (ви ж пишіть коментарі в кожному комітет?).

PHPUnit

Тести вже були в проекті, але я нагадаю як їх підключати:

{
“require-dev”: {
“phpunit/phpunit”: “~4.7”,
}
}

Запуск тестів зазнав невеликі зміни – додана генерація покриття в XML (на даний момент для PHP 7.0 xdebug автоматом не встановлюється, тому що “якщо че” – встановлюйте через PECL):

before_script:
– mkdir .reports
script:
– php vendor/bin/phpunit –configuration ./phpunit.xml.dist –coverage-clover=.reports/clover.xml –coverage-xml=.reports/coverage

Конфігурація PHPDox так само була змінена:

PHP_CodeSniffer

Утиліта аналізу коду PHP_CodeSniffer вже використовувалася в проекті, підключається вона через composer:

{
“require-dev”: {
“squizlabs/php_codesniffer”: “~2.3”
}
}

Конфігураційний файл для перевірки вихідного коду і тестів на відповідність стандартам PSR1 і PSR2 виглядає ось так:

The coding standard for Bluz project
./src
./tests/src
./tests/src/Fixtures
./tests/src/Common/Fixtures

Запускаємо:

script:
# Code style
– php vendor/bin/phpcs –report=xml –report-file=.reports/phpcs.xml

Підключаємо результати до PHPDox:

У мене білд “ламається”, якщо зі стандартами є проблеми, у вас же поведінка CI може відрізнятися від мого, і тоді проблемні місця будуть відображені в документації (напевно 🙂

PHPLoc

Підключаємо:

{
“require-dev”: {
“phploc/phploc”: “*”
}
}

Запускаємо:

script:
# Lines of code and etc
– php vendor/bin/phploc –log-xml=.reports/phploc.xml src

Аналізуємо результати в PHPDox:

PHPMessDetector

Підключаємо:

{
“require-dev”: {
“phpmd/phpmd”: “*”
}
}

Запускаємо:

script:
# Mess detection
– php vendor/bin/phpmd ./src xml codesize,unusedcode,naming –reportfile .reports/phpmd.xml || true

Тут довелося піти на хитрість – у разі якщо phpmd знаходить якісь порушення правил (приміром занадто коротке ім’я змінної), то він поверне exit code дорівнює 2, що “ламає” білд, тому довелося його заглушити, а всі знайдені проблеми “згодувати” в документацію.

Аналізуємо результати в PHPDox:

Результат

Ось що у мене вийшло в результаті всіх описаних маніпуляцій – дивіться і щупайте – http://bluzphp.github.io/.
Вихідні файли конфігурацій доступні в репозиторії на GitHub:

  • composer.json
  • .travis.yml
  • .travis.sh
  • phpdox.xml

Один момент

Є в даного рішення один недолік – немає в паблике версионирования документації (логи змін не в рахунок), щоб вирішити дану проблему, потрібно не так багато – додавати документацію для кожного тегу (потрібно змінна $TRAVIS_TAG), а в репозиторії документації підхоплювати всі нові директорії (ніби як функціоналу сторінок вистачить для цього), але це поки відкладено в довгий ящик.

P. S. При написанні даного посібника використано матеріали зі статті Publier automatiquement une PHPDoc sur GitHub avec Travis CI