Using GitHub Actions to Publish Doxygen Docs to GitHub Pages
#actionshackathon21#productivity#github
Jonah Lawrence

Jonah Lawrence @denvercoder1

About: 💻 Full Stack Developer 🐙 @DenverCoder1 📺 YouTube · Dev Pro Tips

Location:
Colorado, USA
Joined:
Oct 26, 2020

Using GitHub Actions to Publish Doxygen Docs to GitHub Pages

Publish Date: Dec 6 '21
9 0

My Workflow

Marketplace screenshot

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
Enter fullscreen mode Exit fullscreen mode

Submission Category:

DIY Deployments

Yaml File or Link to Code

GitHub logo 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 }}
Enter fullscreen mode Exit fullscreen mode

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"
Enter fullscreen mode Exit fullscreen mode

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"
Enter fullscreen mode Exit fullscreen mode

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

runs:
  using: "composite"
  steps:
Enter fullscreen mode Exit fullscreen mode

The following are the steps added to the action:

1. Checkout repository 

    - name: Checkout repository
      uses: actions/checkout@v2
      with:
        submodules: "true"
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

Doxygen is installed by running apt-get install

3. Generate Doxygen Documentation 

    - name: Generate Doxygen Documentation
      run: doxygen
      shell: bash
Enter fullscreen mode Exit fullscreen mode

Doxygen documentation is generated by running doxygen.

4. Create .nojekyll 

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

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 }}
Enter fullscreen mode Exit fullscreen mode

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.

Comments 0 total

    Add comment