My Workflow
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
Submission Category:
DIY Deployments
Yaml File or Link to Code
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 }}
Options
-
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β¦
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"
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"
This action is a composite action. First we add a runs
property using composite
, then we add the steps.
runs:
using: "composite"
steps:
The following are the steps added to the action:
1. Checkout repository
- name: Checkout repository
uses: actions/checkout@v2
with:
submodules: "true"
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
Doxygen is installed by running apt-get install
3. Generate Doxygen Documentation
- name: Generate Doxygen Documentation
run: doxygen
shell: bash
Doxygen documentation is generated by running doxygen
.
4. Create .nojekyll
- 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
- 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 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.
Top comments (0)