Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/denvercoder1/doxygen-github-pages-action
GitHub Action for deploying Doxygen documentation to a GitHub pages branch
https://github.com/denvercoder1/doxygen-github-pages-action
actions actionshackathon21 deployment-automation doxygen github-workflows hacktoberfest
Last synced: about 2 hours ago
JSON representation
GitHub Action for deploying Doxygen documentation to a GitHub pages branch
- Host: GitHub
- URL: https://github.com/denvercoder1/doxygen-github-pages-action
- Owner: DenverCoder1
- License: mit
- Created: 2021-12-06T03:19:32.000Z (almost 3 years ago)
- Default Branch: main
- Last Pushed: 2024-09-26T18:42:35.000Z (about 2 months ago)
- Last Synced: 2024-11-10T02:34:37.243Z (6 days ago)
- Topics: actions, actionshackathon21, deployment-automation, doxygen, github-workflows, hacktoberfest
- Homepage:
- Size: 23.4 KB
- Stars: 75
- Watchers: 2
- Forks: 16
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# 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
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](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`.
- `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:
```yml
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](https://github.com/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:
```bash
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.
```bash
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.
```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`.
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](LICENSE)
## Support
If you like this project, give it a ⭐ and share it with friends!