Skip to content

Automatic deployment Doxygen documentation

Jump to bottom
ACarfi edited this page Nov 8, 2018 · 4 revisions

This tutorial describes how to configure a repository to deploy automatically he documentation generated by Doxygen.

It is derived from the original work of Jeroen de Bruijn

Signup for Travis CI and add your repository

Create an account at Travis CI. Turn on Travis for your repository.

Provide Travis CI with an encrypted credential for publishing

This step provides Travis CI with the ability to deploy to gh-pages without making the required credentials public. The solution for this is to use a personal access token for GitHub and use Travis' encryption support.

Generate a personal access token for GitHub

  1. In GitHub, go to settings and Personal access tokens
  2. Click Generate a new token and fill in the description. e.g. <your_repo> Travis CI Documentation
  3. If the repository is public select as scope public_repo. If your repository is private select as scope repo
  4. Click Generate token
  5. Copy the generated token

Add the secure variable to Travis CI

  1. In Travis CI, go to the repository settings
  2. In the Environment Variables section write in the Name field GH_REPO_TOKEN
  3. Past the copied token in the Value field
  4. Make sure that the Display value in build log is switched off
  5. Click on Add

Clone your repository

 git clone https://github.com/user-name/repository-name.git

Create a clean gh-pages branch

cd /path/to/repository 
git checkout --orphan gh-pages
git commit -m "First commit"
git push origin gh-pages
git rm -rf .
git commit -m "Clean start"
git push origin gh-pages

Add the necessary files in the repository folder

Switch on the master branch

git checkout master

and copy in your repository folder the two files:

  • Doxyfile, the Doxygen configuration file
  • .travis.yml, the Travis CI configuration file
  • Readme.md, the description of your repository that will be used as the main page for Doxygen

Modify the Doxyfile

In the Doxyfile complete the field identified with the #toDo tag

  • PROJECT_NAME
  • PROJECT_BRIEF

Commit and Push the changes

git add .
git commit -m "Doxyfile and Travis.yml
git push

When you do the push Travis CI automatically start compiling the Doxygen and if, the process terminates without errors, published on the gh-pages branch the Doxygen documentation. Thanks to github pages the documentation will be available online at the address

https://user-name.github.io/repository-name/

Note: The website published by github pages can take a while to appear and refresh changes

Example repository

An example of a repository that is using this technique is

gesture-based-controller

the resulting website

emarolab.github.io/gesture-based-controller/

Doxygen Note

Doxygen support by default: C, C++, C#, Objective-C, IDL, Java, VHDL, PHP, Python, Tcl, Fortran, and D. If you do not use Java or Python remember to set to NO the OPTIMIZE_OUTPUT_JAVA field in the Doxyfile.

Author

Alessandro Carfì e-mail: [email protected]

This work derived from the original work of Jeroen de Bruijn

Clone this wiki locally