RootsLabs

Votre projet PHP utilise Travis CI pour l’intégration continue. Vous souhaitez générer une documentation PHP via PHPDoc et la fournir à vos utilisateurs. Et si on utilisait les GitHub Pages pour vous héberger ? Dans cet article, je vais vous montrer comment utiliser Travis CI pour générer la documentation avec PHPDoc et la pousser vers les pages GitHub.

Pré-Requis

Tout d’abord, certains pré-requis sont indispensables :

• Avez-vous une branche gh-pages sur votre dépôt Git ?
• Est ce que Travis-CI est activé pour votre projet ?
• Avez-vous créé un token d’accès pour pouvoir publier la documentation ?
• Avez-vous installé la gem Travis sur votre poste ?

  gem install travis

Token d’acces et .travis.yml

Après avoir récupéré votre token d’accès, on va le crypter pour que Travis puisse l’utiliser :

[user@computer dirProject]$ travis encrypt GH_TOKEN=<votre_token_dacces>
Please add the following to your .travis.yml file:

  secure: "<votre token crypté>"

Pro Tip: You can add it automatically by running with --add.

Après avoir récupéré ce token crypté, on va l’ajouter au fichier .travis.yml où l’on va mettre juste après la section lié aux versions de PHP :

env:
  global:
  - secure: "<votre token crypté>"

PHPDoc et .travis.yml

Maintenant que notre token d’accès est crypté, on va installer PHPDoc. Pour cela, on va utiliser la section du composer.json nommé « require-dev » pour l’installer :

"require-dev": {
    "phpdocumentor/phpdocumentor":"2.*"
}

Après avoir avoir géré l’installation de PHPDocumentor, on va modifier le fichier .travis.yml pour gérer la génération :

before_script:
  ## Composer : Mise à jour et Installation des pre-requis
  - composer selfupdate --quiet
  - composer install -n --prefer-source --dev
  ## PHPDocumentor : Dossier de sortie
  - mkdir -p build/docs

script:
  ## PHPDocumentor : Generation de la documentation dans le dossier de sortie
  - vendor/bin/phpdoc.php -d ./src -t ./build/docs

after_script:
 ## PHPDocumentor : Upload vers les GitHub Pages
 - bash .travis_shell_after_success.sh

Pour la partie after_script, on utilise un script maison qui récupère le projet, nettoie et copie la documentation avant de l’envoyer vers GitHub.

#!/bin/bash

#echo "--DEBUG--"
#echo "TRAVIS_REPO_SLUG: $TRAVIS_REPO_SLUG"
#echo "TRAVIS_PHP_VERSION: $TRAVIS_PHP_VERSION"
#echo "TRAVIS_PULL_REQUEST: $TRAVIS_PULL_REQUEST"

if [ "$TRAVIS_REPO_SLUG" == "<Votre depot>" ] && [ "$TRAVIS_PULL_REQUEST" == "false" ] && [ "$TRAVIS_PHP_VERSION" == "<Version de PHP pour la generation>" ]; then

  echo -e "Publishing PHPDoc...\n"
  ## Copie de la documentation generee dans le $HOME
  cp -R build/docs $HOME/docs-latest

  cd $HOME
  ## Initialisation et recuperation de la branche gh-pages du depot Git
  git config --global user.email "travis@travis-ci.org"
  git config --global user.name "travis-ci"
  git clone --quiet --branch=gh-pages https://${GH_TOKEN}@github.com/<Votre depot> gh-pages > /dev/null

  cd gh-pages
  
  ## Suppression de l'ancienne version
  git rm -rf ./docs/$TRAVIS_BRANCH

  ## Création des dossiers
  mkdir docs
  cd docs
  mkdir $TRAVIS_BRANCH

  ## Copie de la nouvelle version
  cp -Rf $HOME/docs-latest/* ./$TRAVIS_BRANCH/

  ## On ajoute tout
  git add -f .
  ## On commit
  git commit -m "PHPDocumentor (Travis Build : $TRAVIS_BUILD_NUMBER  - Branch : $TRAVIS_BRANCH)"
  ## On push
  git push -fq origin gh-pages > /dev/null
  ## Et c est en ligne !
  echo -e "Published PHPDoc to gh-pages.\n"

fi

Conclusion

Et voilà, désormais, on aura un dossier de documentation pour chaque branche du projet. Ainsi la documentation de la branche develop n’écrasera pas la documentation de la branche master à chaque commit, et un développeur saura facilement s’y retrouver. Maintenant que l’on sait pusher des fichiers sur GitHub depuis Travis-CI, cela ouvre de nouvelles possibilités : rapport de couverture de code en HTML, script qui convertit du Markdown en HTML avant de le pousser, etc…