Using GitHub Actions to Publish Doxygen Docs to GitHub Pages

My Workflow

Doxygen GitHub Pages Deploy Action is a new GitHub action for automating the process of making documentation using Doxygen and publishing it to GitHub Pages.

This action is a composite action using shell scripts for installing necessary tools and preparing docs and makes use of JamesIves/github-pages-deploy-action for deploying the docs to a GitHub Pages branch.

Example Usage

name: Doxygen GitHub Pages Deploy Action

on:
  push:
    branches:
      - main
  workflow_dispatch:

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: DenverCoder1/doxygen-github-pages-action@v1
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          branch: gh-pages
          folder: docs/html

Submission Category:

DIY Deployments

Yaml File or Link to Code

DenverCoder1 / doxygen-github-pages-action

GitHub Action for deploying Doxygen documentation to a GitHub pages branch

Doxygen GitHub Pages Deploy Action

GitHub Action for making and deploying Doxygen documentation to a GitHub pages branch

Basic Usage

To deploy docs on every push to the main branch, create a new file in the .github/workflows/ directory called doxygen-gh-pages.yml with the following contents:

name: Doxygen GitHub Pages Deploy Action

on:
  push:
    branches:
      - main

jobs:
  deploy:
    runs-on: ubuntu-latest
    permissions:
      contents: write
    steps:
      - uses: DenverCoder1/doxygen-github-pages-action@v2.0.0
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}

Options

• github_token (required): GitHub token for pushing to repo. See the docs for more info.
• branch (optional): Branch to deploy to. Defaults to gh-pages.
• folder (optional): Folder where the docs are built. Defaults to docs/html.
• config_file (optional): Path of the Doxygen configuration file. Defaults to Doxyfile.
• target_folder (optional): Directory within the deployment branch to push to. Defaults to empty (root).
• doxygen_version (optional): Version…

View on GitHub

In the Making

First I needed to create a new repo with an action.yml to start making the composite action.

This action is the first action I have listed on the Marketplace. In order to set up the listing properly, the following data appears at the top of the action file:

name: 'Doxygen GitHub Pages Deploy Action'
author: 'Jonah Lawrence'
description: 'Make docs with Doxygen then deploy the generated HTML to GitHub pages'
branding:
  icon: "upload-cloud"
  color: "purple"

Since the github_token, folder, and branch used for deployment should be configurable, these three inputs were added to the action to allow these to be set in a workflow using the with: property.

inputs:
  github_token:
    description: 'A GitHub token for pushing to the repo. Example: https://git.io/passing-token'
    required: true
  branch:
    description: 'Branch name for pushing GitHub pages files'
    required: true
    default: "gh-pages"
  folder:
    description: 'Folder where Doxygen will generate the HTML build files'
    required: true
    default: "docs/html"

This action is a composite action. First we add a runs property using composite, then we add the steps.

runs:
  using: "composite"
  steps:

The following are the steps added to the action:

1. Checkout repository

    - name: Checkout repository
      uses: actions/checkout@v2
      with:
        submodules: "true"

The actions/checkout step is used to checkout the repository with any submodules.

2. Install Doxygen

    - name: Install Doxygen
      run: sudo apt-get install doxygen -y
      shell: bash

Doxygen is installed by running apt-get install

3. Generate Doxygen Documentation

    - name: Generate Doxygen Documentation
      run: doxygen
      shell: bash

Doxygen documentation is generated by running doxygen.

4. Create .nojekyll

    - name: Create .nojekyll
      run: touch ${{ inputs.folder }}/.nojekyll
      shell: bash

Creating a .nojekyll file ensures pages with underscores work on GitHub Pages.

The folder where the documentation is built is where the .nojekyll file will be created. The folder input is used for this purpose.

5. Deploy to GitHub Pages

    - name: Deploy to GitHub Pages
      uses: JamesIves/github-pages-deploy-action@3.7.1
      with:
        github_token: ${{ inputs.github_token }}
        branch: ${{ inputs.branch }}
        folder: ${{ inputs.folder }}

The JamesIves/github-pages-deploy-action action is used to deploy the documentation to GitHub Pages.

The folder input option determines which folder to deploy. By default, it is docs/html.

The branch input option determines which branch to deploy to. By default, it is gh-pages.

Additional Resources / Info

To see it in action, I have set up the action to run on my C-Workshop GitHub repository.