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

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 }}

• 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

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/doxygen-github-pages-action@v2.0.0
 with:
 github_token: ${{ secrets.GITHUB_TOKEN }}
 branch: gh-pages
 folder: docs/html
 config_file: Doxyfile
 doxygen_version: 1.9.6

This action is a composite action containing the following steps:

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

Doxygen and Graphviz are installed by running the following command:

sudo apt-get install doxygen graphviz -y

Doxygen documentation is generated by running the following command.

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

doxygen Doxyfile

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

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.

This work is under an MIT license

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