Using GitHub Actions to Publish Doxygen Docs to GitHub Pages
Tags: actionshackathon21, productivity, github
Published: 2021-12-06 06:34:03

[Instructions]: # (To submit to the GitHub Actions x DEV Hackathon 2021, please fill out all sections.)


### My Workflow
[Note]: # (Please make sure the project links to the appropriate GitHub Actions repository, and includes [an open source license](https://choosealicense.com/) and README.)

[![Marketplace screenshot](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/kxxu8dgjat4dmlrz1pde.png)](https://github.com/marketplace/actions/doxygen-github-pages-deploy-action)

[**Doxygen GitHub Pages Deploy Action**](https://github.com/DenverCoder1/doxygen-github-pages-action) is a new GitHub action for automating the process of making documentation using [Doxygen](https://www.doxygen.nl/index.html) and publishing it to [GitHub Pages](https://pages.github.com/).

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](https://github.com/JamesIves/github-pages-deploy-action) for deploying the docs to a GitHub Pages branch.

## Example Usage

```yml
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: 

[Note]: # (Maintainer Must-Haves, DIY Deployments, Interesting IoT, Phone Friendly, or Wacky Wildcards)

DIY Deployments

### Yaml File or Link to Code

[Note]: # (Our markdown editor supports pretty embeds. Try this syntax: `{% github link_to_your_repo %}` to share a GitHub repository)

{% github DenverCoder1/doxygen-github-pages-action %}

### 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](https://github.com/marketplace/actions/doxygen-github-pages-deploy-action). In order to set up the listing properly, the following data appears at the top of the action file:

```yml
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.

```yml
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.

```yml
runs:
  using: "composite"
  steps:
```

The following are the steps added to the action:

### 1. Checkout repository

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

The [actions/checkout](https://github.com/actions/checkout) step is used to checkout the repository with any submodules.

### 2. Install Doxygen

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

Doxygen is installed by running `apt-get install`

### 3. Generate Doxygen Documentation

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

Doxygen documentation is generated by running `doxygen`.

### 4. Create .nojekyll

```yml
    - 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

```yml
    - 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](https://github.com/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

[Note]: # (Be sure to link to any open source projects that are using your workflow!)

To see it in action, I have set up the action to run on my [C-Workshop](https://github.com/DenverCoder1/C-Workshop) GitHub repository.

[Note]: # (Be sure to include the DEV usernames of your collaborators, if any.)

[Reminder]: # (Submissions are due on December 8th, 2021 (11:59 PM PT or 2 AM ET/6 AM UTC on December 9th.)