Publier automatiquement une PHPDoc sur GitHub avec Travis CI

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.

Travis

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…

Cet article Publier automatiquement une PHPDoc sur GitHub avec Travis CI est apparu en premier sur RootsLabs.