denvercoder1 / doxygen-github-pages-action Goto Github PK

View Code? Open in Web Editor NEW

64.0 2.0 14.0 20 KB

GitHub Action for deploying Doxygen documentation to a GitHub pages branch

License: MIT License

actions github-workflows doxygen deployment-automation actionshackathon21 hacktoberfest

doxygen-github-pages-action's Introduction

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
    steps:
      - uses: DenverCoder1/[email protected]
        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 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).

Advanced Usage

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

About this Action

This action is a composite action containing the following steps:

1. Checkout repository

The 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:

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.

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.

touch docs/html/.nojekyll

5. Deploy to GitHub Pages

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.

License

This work is under an MIT license

Support

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

doxygen-github-pages-action's People

Contributors

Stargazers

Watchers

Forkers

nnoelwess-soft arran4 teocala m1ntyskye talespire-modding mi4bt born-studios reworks-org kangrui-hiverlab gob52 gab-k chegewara twardokus justenoughmod

doxygen-github-pages-action's Issues

idea: graphviz support

the yml file does not appear to install graphviz, meaning that attempting to use graphviz will most likely error out.

There is nothing to commit; Exitting early

Hi,
I've tried to use this action for my project, but was met with the following message at the end of the action run:

There is nothing to commit. Exiting early… 📭

Unfortunately I didn't notice any error beforehand; everything seems to go smoothly up until the point where it tries to commit the documentation to the gh-pages branch.

You can see the action log here.

Could you maybe look at the logs and see what's wrong?

--
Thanks a lot,
Jozef

Is deployment to a subdirectory possible?

Currently this action seems to overwrite the complete gh-pages repository, correct?

Is there a possibility to deploy the Doxygen docu only to a subdirectory of gh-pages - and leave the rest of the website as it is?
Best regards, Wolfgang

Something looks wrong with 'dot'

Even graphviz is installed, the action is complaining about 'dot'.

sh: 1: dot: not found
error: Problems running dot: exit code=127, command='dot', arguments='"/home/runner/work/PVRouter-3-phase/PVRouter-3-phase/docs/html/class__rg__OffsetForce_a2d0fe1a08e4856f38a91f26b46066733_cgraph.dot" -Tpng -o "/home/runner/work/PVRouter-3-phase/PVRouter-3-phase/docs/html/class__rg__OffsetForce_a2d0fe1a08e4856f38a91f26b46066733_cgraph.png" -Tcmapx -o "/home/runner/work/PVRouter-3-phase/PVRouter-3-phase/docs/html/class__rg__OffsetForce_a2d0fe1a08e4856f38a91f26b46066733_cgraph.map"'```

Plugging the `git` version into the `PROJECT_NUMBER`

I am wondering whether the action can be instructed to use a custom script that simply calls doxygen with the PROJECT_NUMBER being exported using the git version or a tag name.

If not, can this be done otherwise?

Otherwise, and although the action implies that the documentation matches the HEAD revision, we do not have any indication of the version that we are looking at.

Thanks for maintaining this tool.

Permission to denied error when deploying

Hi,
thanks for developing and maintaining this tool.

I am trying to use it for a repository that I contribute to. So far, my effort has been unsuccessful. I am getting an

remote: Permission to SlicerDMRI/SlicerDMRI.git denied to github-actions[bot].
fatal: unable to access 'https://github.com/SlicerDMRI/SlicerDMRI.git/': The requested URL returned error: 403

error at the moment where the deployment should take place: https://github.com/SlicerDMRI/SlicerDMRI/actions/runs/6685911043/job/18164701923?pr=195#step:2:787

I have granted write permissions to the workflow, actions do have write permissions in the repository settings, and the GitHub pages Build and deployment is configured to deploy from the gh-pages branch; I have also tried setting it to GitHub Actions with the same result.

What am I missing?

Thanks.

Obvious issues with my usage?

Is there anything obviously wrong with my usage here:
https://github.com/DMJC/Linwarrior3D/runs/6237704319?check_suite_focus=true

https://github.com/DMJC/Linwarrior3D/blob/main/.github/workflows/ghpdoxy.yaml

Please upgrade JamesIves/[email protected] to 4.4.1

JamesIves/[email protected] is obsolet and generates a warning about Node.js.

Please upgrade to 4.4.1 which is the current version.

The process '/usr/bin/rsync' failed with exit code 24

It suddenly stopped working for me:

https://github.com/mupfdev/GameComms/actions/runs/6895504126/job/18759587329#step:2:845

Is this a bug or a temporary issue?

Best regards,
Michael

Doxygen not going through all C++ files

Hi, I checked my Doxyfile, and it works, with an output to docs/html.

I use this into my existing github action

    - name: Doxygen GitHub Pages Deploy Action
      uses: DenverCoder1/doxygen-github-pages-action@v1
      with:
        github_token: ${{ secrets.GITHUB_TOKEN }}

after my tests pass.

What is possibly problematic? Token? I haven't set any as I saw somewhere it should be automatic. Is it true?

Also my branch gh-pages looks like this :

Thanks!

cannot touch 'docs/html/.nojekyll': No such file or directory

after a push i get this message

Run touch docs/html/.nojekyll
touch: cannot touch 'docs/html/.nojekyll': No such file or directory
Error: Process completed with exit code [1](https://github.com/virtuosonic/libcdkpp/actions/runs/5989466679/job/16245682707#step:4:1).

This is my workflow file

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

Doesn't create folder if it doesn't exist

I needed to add:

      - name: mkdir
        run: mkdir -p docs/html

Above to get it to work.

Actually that failed b/c of a tree change or context change, I needed to add a .gitkeep to the folder to get past that point. Perhaps a "create-folder-if-not-exist' option which defaults to true?