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
steps:
- uses: DenverCoder1/[email protected]
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 togh-pages
.folder
(optional): Folder where the docs are built. Defaults todocs/html
.config_file
(optional): Path of the Doxygen configuration file. Defaults toDoxyfile
.target_folder
(optional): Directory within the deployment branch to push to. Defaults to empty (root).doxygen_version
(optional): Version of Doxygen to install. Defaults to1.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
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
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!