Deploy Docs

Deploy Documentation

These are documentation for deploying the Doxygen generated HTML Docs to the GitHub Pages static site hosting service, using Travis CI continuous integration service.

A good future improvement would be to switch from Travis CI to GitHub Actions.

They were created for personal documentation, but I am uploading them if anyone else is interested in the process.

Create a gh-pages branch

In your git project folder create a new empty branch called gh-pages on your repository:

git checkout --orphan gh-pages

Delete everything in here, as it will be overwritted:

git rm -rf .

Add the .gitignore file to ignore everything that you don't want to be overwritten.

Add a README.md just to inform this is a docs branch.

Update and push changes:

git add .
git commit -m "Added clean gh-pages branch"
git push --set-upstream origin gh-pages

Travis CI Sign Up

Sign up using your GitHub account on the Travis CI website.

Activate the GitHub repository you want for Travis CI to have access.

Test Travis CI

Add a .travis.yml file to your repository to tell Travis CI what to do:

# Simple yml file to test Travis CI
# Install dependencies
addons:
  apt:
    packages:
      - doxygen
      - doxygen-doc
      - doxygen-latex
      - doxygen-gui
      - graphviz

Add the .travis.yml file to git, commit and push to trigger a Travis CI build:

git add .
git commit -m "Added Travis CI config file"
git push

Check the build status page to see if your build passes or fails according to the return status of the build command by visiting Travis CI and selecting your repository.

Final configuration file

Update .travis.yml in order to deploy to GitHub pages after each push to main:

# Specify system and language
language: generic

# Build only on main
branches:
  only:
    - main

# Install dependencies (Ubuntu 20.04)
dist: focal
addons:
  apt:
    packages:
      - doxygen
      - doxygen-doc
      - doxygen-latex
      - graphviz

# Generate documentation
script:
  make docs

# Deploy docs to GitHub Pages
deploy:
  provider: pages
  skip_cleanup: true
  github_token: $GITHUB_TOKEN
  local_dir: docs/doxygen/html
  on:
    branch: main

Configuration file is available at the repository: .travis.yml

GitHub Token

Generate a Personal Access Token from GitHub's Developers Settings. Make sure to save the token, because you wan't be able to see it again.

Add token to repository in Travis CI

In order to have the token securely saved and not exposed to the public, save the token in an environmental variable on the Repository Settings on Travis CI.

Go to Your Project -> Settings -> Environment Variables and save the token as GITHUB_TOKEN.

Deploy Docs to GitHub pages

Just make some changes, add, commit and push from the main branch in order to build.

You can find info about the build status in the Travis CI website.

Also, see changes in the GitHub pages after its been deployed.

Previous Page

Generate Docs