TIL: auto-deploy doxygen to GitHub Pages

GitHub Actions and GitHub Pages provide a convenient set of tools for publishing automatically generated HTML documentation for public projects. For my project ccask the documentation is generated using Doxygen and published on GH Pages here.

The bulk of the process is handled by this GH Actions workflow:

name: Doxygen
permissions: 
  contents: write
on:
  push:
    branches: [ "main" ]
  workflow_dispatch:


jobs:
  docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: install doxygen
        run: sudo apt-get install -y doxygen

      - name: Run doxygen
        run: doxygen Doxyfile

      - name: Deploy 🚀
        uses: JamesIves/github-pages-deploy-action@v4.3.3
        with:
          branch: gh-pages # The branch the action should deploy to.
          folder: html # The folder the action should deploy.

Important notes:

• The permissions must be set to write to allow the action JamesIves/github-pages-deploy-action to run.
• In your GH repo’s settings, you must enable GH Pages and set the deployment to run from the gh-pages branch and the root folder.
• To properly generate documentation with Doxygen, each C file that contains documentation you want published must include a @file directive – I missed this!
• Additionally ensure that the INPUT setting is properly set for your project in the Doxyfile.

Tags: til github devops c doxygen