-
Notifications
You must be signed in to change notification settings - Fork 16
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
1 parent
7b72956
commit 2f7ae79
Showing
1 changed file
with
104 additions
and
2 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,2 +1,104 @@ | ||
# 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: | ||
|
||
```yml | ||
name: Doxygen GitHub Pages Deploy Action | ||
|
||
on: | ||
push: | ||
branches: | ||
- main | ||
|
||
jobs: | ||
deploy: | ||
runs-on: ubuntu-latest | ||
steps: | ||
- uses: DenverCoder1/doxygen-github-pages-action@v1 | ||
with: | ||
github_token: ${{ secrets.GITHUB_TOKEN }} | ||
``` | ||
## Options | ||
- `github_token` (required): GitHub token for pushing to repo. See the [docs](https://git.io/passing-token) 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`. | ||
|
||
## Advanced Usage | ||
|
||
Here is an example of a `.github/workflows/doxygen-gh-pages.yml` file with more advanced configuration: | ||
|
||
```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 | ||
``` | ||
|
||
## About this Action | ||
|
||
This action is a composite action containing the following steps: | ||
|
||
### 1. Checkout repository | ||
|
||
The [actions/checkout](https://github.com/actions/checkout) step is used to checkout the repository with any submodules. | ||
|
||
### 2. Install Doxygen | ||
|
||
Doxygen is installed by running the following command: | ||
|
||
```bash | ||
sudo apt-get install doxygen -y | ||
``` | ||
|
||
### 3. Generate Doxygen Documentation | ||
|
||
Doxygen documentation is generated by running the following command: | ||
|
||
```bash | ||
doxygen | ||
``` | ||
|
||
### 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. | ||
|
||
```bash | ||
touch docs/html/.nojekyll | ||
``` | ||
|
||
### 5. Deploy to GitHub Pages | ||
|
||
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` 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`. | ||
|
||
## License | ||
|
||
This work is under an [MIT license](LICENSE) | ||
|
||
## Support | ||
|
||
If you like this project, give it a ⭐ and share it with friends! |