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/[email protected]
        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 of Doxygen to install. Defaults to 1.9.6. NOTE - only works with 1.9.3 and higher versions

Advanced Usage

Here is an example of a .github/workflows/doxygen-gh-pages.yml file with more advanced configuration:

name: Doxygen GitHub Pages Deploy Action

on:
  push:
    branches:
      - main
  workflow_dispatch:

jobs:
  deploy:
    runs-on: ubuntu-latest
    permissions:
      contents: write
    steps:
      - uses: DenverCoder1/[email protected]
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          branch: gh-pages
          folder: docs/html
          config_file: Doxyfile
          doxygen_version: 1.9.6

About this Action

This action is a composite action containing the following steps:

1. Checkout repository

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

2. Install Doxygen

Doxygen and Graphviz are installed by running the following command:

sudo apt-get install doxygen graphviz -y

3. Generate Doxygen Documentation

Doxygen documentation is generated by running the following command.

Set the config_file input option to change Doxyfile to a different filename.

doxygen Doxyfile

4. Create .nojekyll

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

Set the folder input option to change docs/html to a different folder.

touch docs/html/.nojekyll

5. Deploy to GitHub Pages

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

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

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

The target_folder option determines which directory in the deployment branch to push to. By default, the root of the branch is overwritten.

License

This work is under an MIT license

Support

If you like this project, give it a ⭐ and share it with friends!