e
mattnotmitt / doxygen-action Goto Github PK
View Code? Open in Web Editor NEWGitHub Action for generating Doxygen documentation for your projects.
License: MIT License
GitHub Action for generating Doxygen documentation for your projects.
License: MIT License
e
I am working on a larger coding project and we are looking for a method that can automatically update our doxygen-generated documentation. Our project is physics-related, so there are several places where having equations is helpful for documenting the code.
I'm not familiar with GitHub actions, so I'm not sure if this docker image you are using has LaTeX installed in it.
I am building my doxygen webpages locally on PopOS with doxygen v1.9.1 and I have set doxygen-action to use the same:
- name: build fukahome doxy
uses: mattnotmitt/[email protected]
with:
working-directory: './'
doxyfile-path: 'website.dox'
However, when the website gets built with doxygen-action, the sidebar tree view no longer groups subpages under pages as it does when I build the doxygen site locally. Originally I was using [email protected] which caused some issues which was later identified to be caused by a newer version of doxygen, but now I'm not sure what could be causing this.
Any ideas?
There seems to be an issue with the enable-latex: true
option.
Works fine with enable-latex: false
.
Any idea what I am doing wrong?
name: CI/CD
on:
push:
branches:
- latex-test
jobs:
generate_docu:
runs-on: ubuntu-latest
steps:
- name: Checkout Repository
uses: actions/checkout@v1
- name: Install and Build Doxygen
uses: mattnotmitt/[email protected]
with:
working-directory: "./Docs"
doxyfile-path: "Doxygen"
enable-latex: true
- name: Clean Up Source Files
run: |
rm -rf ./Docs/Doxygen
Output is:
...
Generating example index...
finalizing index lists...
writing tag file...
Running plantuml with JAVA...
lookup cache used 19238/65536 hits=184810 misses=21914
finished...
/entrypoint.sh: cd: line 36: can't cd to /latex: No such file or directory
make: *** No targets specified and no makefile found. Stop.
Greetings, like the action. Worked pretty flawlessly once I figured it out.
I am not sure if I am unique, but I like to specify things by full paths to be sure I have things specified correctly.
so, in my workflow, I created a directory to hold the output, and then did some search & replace on the doxyfile to match.
mkdir -p ${{ github.workspace }}/doxygen-output
sed -i 's|@CMAKE_CURRENT_BINARY_DIR@|${{ github.workspace }}/doxygen-output|g' ${{ github.workspace }}/production/docs/doxyfile
sed -i 's|@CMAKE_CURRENT_SOURCE_DIR@/../|${{ github.workspace }}/production|g' ${{ github.workspace }}/production/docs/doxyfile
After getting some errors, it took me a bit to figure out that I needed to replace ${{ github.workspace }}
with /github/workspace
as it was being mounted inside a docker container.
That might be something you want to point out for people using full paths.
Doxygen v1.9.6 got released lately. Would be cool to use it in my documentation.
Thanks for the GitHub action.
The action can't find my Doxyfile which is in the repository root. How can i get it to run?
'doxyfile-path'
Required Path of the Doxyfile relative to the repository root. Default: ./Doxyfile.
jobs:
doxygen:
runs-on: ubuntu-latest
steps:
- uses: mattnotmitt/doxygen-action@v1
with:
doxyfile-path: ./Doxyfile
I'm trying to get plantuml images generated with doxygen.
I've added additional-packages: plantuml
to the action yaml but it doenst seem to start the generation of diagrams :(
Logging shows the following error:
/github/workspace/src/Base.h:43: warning: ignoring \startuml command because PLANTUML_JAR_PATH is not set
According to the Doxygen documentation (https://www.doxygen.nl/manual/commands.html#cmdstartuml), the location of the plantUML jar should be specified in a PLANTUML_JAR_PATH configuration setting.
What should I set this variable to, where is the additional package installed?
Running this step is quite slow and adds an easy 3 minutes to my github automation that has to run for every web rebuild. Is it possible to cache the font downloads in any way? I know github actions has a cache system but im not sure how i would have to set that up to help here or if it would even help
Thank you a lot for such a wonderful action!
In my initial version of workflow, I wrote the followings:
- name: Clone Kerbal
uses: actions/checkout@v4
with:
repository: WentsingNee/Kerbal
path: Kerbal
submodules: 'true'
- name: Run Doxygen
uses: mattnotmitt/[email protected]
with:
working-directory: '${{github.workspace}}/Kerbal/doxygen'
doxyfile-path: 'Doxyfile'
but the log said that the directory cannot be found:
Job Clone Kerbal:
...
/usr/bin/git config --global --add safe.directory /home/runner/work/Kerbal/Kerbal/Kerbal
...
Job Run Doxygen:
...
+ '[' '!' -d /home/runner/work/Kerbal/Kerbal/Kerbal/doxygen ]
+ echo 'Path /home/runner/work/Kerbal/Kerbal/Kerbal/doxygen could not be found!'
Path /home/runner/work/Kerbal/Kerbal/Kerbal/doxygen could not be found!
+ exit 1
I have to change the line
working-directory: '${{github.workspace}}/Kerbal/doxygen'
to
working-directory: 'Kerbal/doxygen'
and finally solve that problem
I suggest that you can mention this issue in readme to help the latecomers and save their time
2022-05-14T06:40:59.1968197Z ##[group]Run mattnotmitt/doxygen-action@v1
2022-05-14T06:40:59.1968539Z with:
2022-05-14T06:40:59.1968774Z doxyfile-path: doc/Doxyfile
2022-05-14T06:40:59.1969139Z working-directory: .
2022-05-14T06:40:59.1969449Z enable-latex: false
2022-05-14T06:40:59.1969676Z ##[endgroup]
2022-05-14T06:40:59.2173292Z ##[command]/usr/bin/docker run --name d2ec7b24907a844fda0230cc791f8b6fd_1df20f --label 08450d --workdir /github/workspace --rm -e INPUT_DOXYFILE-PATH -e INPUT_WORKING-DIRECTORY -e INPUT_ENABLE-LATEX -e INPUT_ADDITIONAL-PACKAGES -e HOME -e GITHUB_JOB -e GITHUB_REF -e GITHUB_SHA -e GITHUB_REPOSITORY -e GITHUB_REPOSITORY_OWNER -e GITHUB_RUN_ID -e GITHUB_RUN_NUMBER -e GITHUB_RETENTION_DAYS -e GITHUB_RUN_ATTEMPT -e GITHUB_ACTOR -e GITHUB_WORKFLOW -e GITHUB_HEAD_REF -e GITHUB_BASE_REF -e GITHUB_EVENT_NAME -e GITHUB_SERVER_URL -e GITHUB_API_URL -e GITHUB_GRAPHQL_URL -e GITHUB_REF_NAME -e GITHUB_REF_PROTECTED -e GITHUB_REF_TYPE -e GITHUB_WORKSPACE -e GITHUB_ACTION -e GITHUB_EVENT_PATH -e GITHUB_ACTION_REPOSITORY -e GITHUB_ACTION_REF -e GITHUB_PATH -e GITHUB_ENV -e GITHUB_STEP_SUMMARY -e RUNNER_OS -e RUNNER_ARCH -e RUNNER_NAME -e RUNNER_TOOL_CACHE -e RUNNER_TEMP -e RUNNER_WORKSPACE -e ACTIONS_RUNTIME_URL -e ACTIONS_RUNTIME_TOKEN -e ACTIONS_CACHE_URL -e GITHUB_ACTIONS=true -e CI=true -v "/var/run/docker.sock":"/var/run/docker.sock" -v "/home/runner/work/_temp/_github_home":"/github/home" -v "/home/runner/work/_temp/_github_workflow":"/github/workflow" -v "/home/runner/work/_temp/_runner_file_commands":"/github/file_commands" -v "/home/runner/work/liba/liba":"/github/workspace" 08450d:2ec7b24907a844fda0230cc791f8b6fd "doc/Doxyfile" "." "false" ""
2022-05-14T06:41:00.3654699Z + '[' '!' -d . ]
2022-05-14T06:41:00.3655341Z fetch https://dl-cdn.alpinelinux.org/alpine/edge/main/x86_64/APKINDEX.tar.gz
2022-05-14T06:41:00.3657529Z + cd .
2022-05-14T06:41:00.3660472Z + '[' '!' -f doc/Doxyfile ]
2022-05-14T06:41:00.3723781Z + '[' '!' -z false ]
2022-05-14T06:41:00.3729506Z + false
2022-05-14T06:41:00.3729930Z + BUILD_LATEX=0
2022-05-14T06:41:00.3730554Z + PACKAGES='doxygen=1.9.3-r1 graphviz ttf-freefont '
2022-05-14T06:41:00.3731107Z + '[' 0 '=' true ]
2022-05-14T06:41:00.3731546Z + apk add 'doxygen=1.9.3-r1' graphviz ttf-freefont
2022-05-14T06:41:00.6681564Z fetch https://dl-cdn.alpinelinux.org/alpine/edge/community/x86_64/APKINDEX.tar.gz
2022-05-14T06:41:01.0412698Z ERROR: unable to select packages:
2022-05-14T06:41:01.0761910Z doxygen-1.9.4-r0:
2022-05-14T06:41:01.0762459Z breaks: world[doxygen=1.9.3-r1]
At https://github.com/step-security/secure-workflows we are building a knowledge-base (KB) of GITHUB_TOKEN permissions needed by different GitHub Actions. When developers try to set minimum token permissions for their workflows, they can use this knowledge-base instead of trying to research permissions needed by each GitHub Action they use.
Below you can see the KB of your GITHUB Action.
name: 'Doxygen Action' # mattnotmitt/doxygen-action
# GITHUB_TOKEN not used
If you think this information is not accurate, or if in the future your GitHub Action starts using a different set of permissions, please create an issue at https://github.com/step-security/secure-workflows/issues to let us know.
This issue is automatically created by our analysis bot, feel free to close after reading :)
GitHub asks users to define workflow permissions, see https://github.blog/changelog/2021-04-20-github-actions-control-permissions-for-github_token/ and https://docs.github.com/en/actions/security-guides/automatic-token-authentication#modifying-the-permissions-for-the-github_token for securing GitHub workflows against supply-chain attacks.
Setting minimum token permissions is also checked for by Open Source Security Foundation (OpenSSF) Scorecards. Scorecards recommend using https://github.com/step-security/secure-workflows so developers can fix this issue in an easier manner.
Spinning up the image (especially when using the LaTeX option) can take the bulk of the time of the action. We should build the image with all of the packages required for anything any user would need while keeping the additional-packages
option to add anything else once the initial image has started up. The LaTeX option would remain but this would simply run the makefile, rather than pulling in the extra dependencies.
Would it possible to deploy documentation to other repository after building?
Looks like alpine released a -r1 version of 1.9.3 so now the builds that use the action @1.9.3 are broken, as they pin the package name with -r0.
It seems like one of the latest changes in the alpine Linux distribution broke the TeX-support. This is the same issue as what #15 tries to fix, but maybe we can find the root cause rather than changing to arch Linux.
My best guess is that these refactorings in April are related:
Thanks for developing this action!
Which version of doxygen does it use? I am getting the following warnings, which I do not get when I run locally with 1.9.2. The workflow is here: https://github.com/natke/onnxruntime/runs/4451892746?check_suite_focus=true
warning: ignoring unsupported tag 'SHOW_HEADERFILE' at line 609, file ./Doxyfile
warning: ignoring unsupported tag 'WARN_IF_INCOMPLETE_DOC' at line 827, file ./Doxyfile
warning: Tag 'CLANG_ASSISTED_PARSING' at line 1169 of file './Doxyfile' belongs to an option that was not enabled at compile time.
To avoid this warning please remove this line from your configuration file or upgrade it using "doxygen -u", or recompile doxygen with this feature enabled.
warning: Tag 'CLANG_ADD_INC_PATHS' at line 1177 of file './Doxyfile' belongs to an option that was not enabled at compile time.
To avoid this warning please remove this line from your configuration file or upgrade it using "doxygen -u", or recompile doxygen with this feature enabled.
warning: Tag 'CLANG_OPTIONS' at line 1185 of file './Doxyfile' belongs to an option that was not enabled at compile time.
To avoid this warning please remove this line from your configuration file or upgrade it using "doxygen -u", or recompile doxygen with this feature enabled.
warning: Tag 'CLANG_DATABASE_PATH' at line 1198 of file './Doxyfile' belongs to an option that was not enabled at compile time.
To avoid this warning please remove this line from your configuration file or upgrade it using "doxygen -u", or recompile doxygen with this feature enabled.
warning: ignoring unsupported tag 'FULL_SIDEBAR' at line 1611, file ./Doxyfile
warning: ignoring unsupported tag 'MATHJAX_VERSION' at line 1694, file ./Doxyfile
I need to install doxypypy from github to build my documentation, but I don't think this is possible via the additional_packages
option.
Is there any way to run a custom script before building the documentation?
Hi there,
Thanks for a wonderful github action! Alas I have encountered a problem.
I do not wish to generate a latex
folder, and ergo my doxygen config file contains GENERATE_LATEX = NO
. This means I do not need to run the final make
command. In fact, I wish to avoid running that command altogether, since my Github Action otherwise encounters an error (! LaTeX Error: File hierarchy.tex not found
) unrelated to this question, which I wish to avoid debugging.
My documentation strings however do include LaTeX formulae, with syntax
\f[
x^2
\f]
This means my html
documentation needs images of the LaTeX formulae, which Doxygen generates with LaTeX. Doxygen performs this even when GENERATE_LATEX = NO
(the flag is very unfortunately named).
Here is my problem. Because my doxygen config file contains GENERATE_LATEX = NO
(to avoid the above unrelated bug), the entrypoint script sets BUILD_LATEX=0
, avoiding the apk
installation of texlive-full
. So while Doxygen is running, the latex
command is undefined. Doxygen will hence complain that
sh: latex: not found
error: Problems running latex. Check your installation or look for typos in _formulas.tex and check _formulas.log!
and be unable to generate the images needed by my html
documentation.
The core of the issue is that you cannot consult the Doxygen config file's GENERATE_LATEX
flag to determine whether or not to build latex. This is because the latex command is sometimes needed by html generation, when latex (document) generation is off.
I think a natural fix is to trust the user's enable-latex
action argument to inform whether or not to build the latex command.
Then, only consult the Doxygen config file's GENERATE_LATEX
to decide whether or not to call the final make
.
I can happily submit this in a pull request
any chance we could get the github env tag about projects' version number into the Doxygen config file's PROJECT_NUMBER
tag?
I know doxygen allows for additional doxygen config files via the config's @INCLUDE
& @INCLUDE_PATH
tags. Maybe you could generate config file for github env vars (version, commit, author, and other stuff) before running doxygen. This would also require altering the default config file's @INCLUDE
and/or @INCLUDE_PATH
tags to accommodate the generated config file (with github env vars).
p.s. I see you're already using doxygen <config_file>
in entrypoint.sh; I doubt that doxygen would support a list of config files as the CLI arg
I use Doxyfile config including the following fragment to make Doxygen always fail if there are errors in my docs:
# If the WARN_AS_ERROR tag is set to YES then doxygen will immediately stop when
# a warning is encountered.
# The default value is: NO.
WARN_AS_ERROR = YES
On the command-line locally, this causes Doxygen to quit early, halting the doc generation process and returning non-success process exit code. I've previously used this technique for docs CI on Travis, but I noticed the docs generation failing doesn't fail the builds on Github Actions when using this action.
Is it feasible to add support for this workflow by exposing the doxygen command's exit code in the Github Action?
I know #7 is already open and is similar to this, but from what I have read on that other thread, what I'm asking about here seems to be something a bit different.
Thanks
When execution fails, i.e. because doxygen file cannot be found, the step is ended and the next step is still executed.
This will also list the Job as succeeded while it obviously has failed
Hi @mattnotmitt
I would like to ask if there is any sample example provided to show how this action should be used. I did as follows but it seems I am using it in a wrong way
doxygen.yml file: https://github.com/JaehyunShim/test/blob/master/.github/workflows/doxygen.yml
Doxyfile: https://github.com/JaehyunShim/test/blob/master/docs/Doxygen/Doxyfile
Action result: https://github.com/JaehyunShim/test/runs/2054847888?check_suite_focus=true#step:3:7
Thank you in advance,
Jaehyun
Hi, I would like to understand if its possible to add PlantUML into the actions via additional packages field, i tried to search for PlantUML plugin in the package but couldnt able to find it.
TIA
Suresh
Hi, when I put
enable-latex: true
in my action file, I receive the warning
Warning: Unexpected input(s) 'enable-latex', valid inputs are ['entryPoint', 'args', 'doxyfile-path', 'working-directory']
and no latex output is generated (only html). I guess I have to push the latex document to my repository too, but just looking at the action output there is no latex command executed. GENERATE_LATEX is set to YES in my Doxyfile.
This is my main.yml:
name: CI
on:
push:
branches: [ master ]
workflow_dispatch:
jobs:
documentation:
runs-on: ubuntu-latest
steps:
# Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
- uses: actions/checkout@v2
- name: Doxygen Action
uses: mattnotmitt/[email protected]
with:
# Working directory
working-directory: "." # default is .
# Path to Doxyfile
doxyfile-path: "./doc/Doxyfile" # default is ./Doxyfile
enable-latex: true
Hi mattnotmitt!
I'm trying to use the action while I have the Doxyfile in a docs
folder on my repo: https://github.com/gmargari/cmake-gtest-ci
name: Documentation
on:
push:
branches: [ master ]
pull_request:
branches: [ master ]
jobs:
job:
name: Documentation
runs-on: ubuntu-latest
steps:
- name: "Run doxygen"
uses: mattnotmitt/[email protected]
with:
working-directory: "docs/"
and I'm getting:
/usr/bin/docker run --name be76db65e21b2a8f4f46e8996f5a075bb0e7ce_53da06 --label be76db --workdir /github/workspace --rm -e INPUT_WORKING-DIRECTORY -e INPUT_DOXYFILE-PATH -e HOME -e GITHUB_JOB -e GITHUB_REF -e GITHUB_SHA -e GITHUB_REPOSITORY -e GITHUB_REPOSITORY_OWNER -e GITHUB_RUN_ID -e GITHUB_RUN_NUMBER -e GITHUB_ACTOR -e GITHUB_WORKFLOW -e GITHUB_HEAD_REF -e GITHUB_BASE_REF -e GITHUB_EVENT_NAME -e GITHUB_WORKSPACE -e GITHUB_ACTION -e GITHUB_EVENT_PATH -e RUNNER_OS -e RUNNER_TOOL_CACHE -e RUNNER_TEMP -e RUNNER_WORKSPACE -e ACTIONS_RUNTIME_URL -e ACTIONS_RUNTIME_TOKEN -e ACTIONS_CACHE_URL -e GITHUB_ACTIONS=true -e CI=true -v "/var/run/docker.sock":"/var/run/docker.sock" -v "/home/runner/work/_temp/_github_home":"/github/home" -v "/home/runner/work/_temp/_github_workflow":"/github/workflow" -v "/home/runner/work/cmake-gtest-ci/cmake-gtest-ci":"/github/workspace" be76db:65e21b2a8f4f46e8996f5a075bb0e7ce "./Doxyfile" "docs/"
/entrypoint.sh: cd: line 5: can't cd to docs/: No such file or directory
Path docs/ could not be found!
File ./Doxyfile could not be found!
error: configuration file ./Doxyfile not found!
I have used this project to build my Doxygen documentation on Github.
This is my .yml file: https://github.com/epics-modules/asyn/blob/master/.github/workflows/publish-docs.yml
The Doxygen documentation builds fine. The source is docs/Doxyfile which specifies that the built HTML output goes in docs/doxygenHTML. This is a listing of the docs directory after the build:
-rw-r--r-- 1 runner docker 110785 Mar 8 20:17 Doxyfile
-rw-r--r-- 1 runner docker 329 Mar 8 20:17 Makefile
drwxr-xr-x 2 root root 12288 Mar 8 20:17 doxygenHTML
-rw-r--r-- 1 runner docker 87 Mar 8 20:17 requirements.txt
drwxr-xr-x 3 runner docker 4096 Mar 8 20:17 source
This is the beginning of the listing of the doxygenHTML directory after the build.
-rw-r--r-- 1 root root 9466 Mar 8 20:17 annotated.html
-rw-r--r-- 1 root root 9125 Mar 8 20:17 asyn_param_type_8h.html
-rw-r--r-- 1 root root 14818 Mar 8 20:17 asyn_param_type_8h_source.html
-rw-r--r-- 1 root root 2923 Mar 8 20:17 asyn_port_client_8cpp.html
-rw-r--r-- 1 root root 14779 Mar 8 20:17 asyn_port_client_8h.html
-rw-r--r-- 1 root root 175441 Mar 8 20:17 asyn_port_client_8h_source.html
-rw-r--r-- 1 root root 1[181](https://github.com/epics-modules/asyn/actions/runs/4368175027/jobs/7640418498#step:8:182)1 Mar 8 20:17 asyn_port_driver_8cpp.html
The file are all there. However, note that they are owned by root, with only read permissions for other users.
The next part of my Github actions is to build Sphinx documentation which is in docs/source.
The github actions then fails when it tries to delete the Doxygen files.
Run sphinx-notes/pages@v2
Started: bash /home/runner/work/_actions/sphinx-notes/pages/v2/main.sh
Initialize various paths
Installing Sphinx
Installing requirements
Creating temp directory
Running Sphinx builder
Setting up git repository
Setting up git configure
No local changes to save
Setting up branch gh-pages
Branch exists, checkout to it
Switched to a new branch 'gh-pages'
branch 'gh-pages' set up to track 'origin/gh-pages'.
warning: failed to remove docs/doxygenHTML/test_asyn_port_driver_main_[8](https://github.com/epics-modules/asyn/actions/runs/4368175027/jobs/7640418498#step:9:9)cpp.html: Permission denied
warning: failed to remove docs/doxygenHTML/nav_fd.png: Permission denied
warning: failed to remove docs/doxygenHTML/classtest_asyn_port_driver.html: Permission denied
warning: failed to remove docs/doxygenHTML/folderclosed.png: Permission denied
warning: failed to remove docs/doxygenHTML/tab_bd.png: Permission denied
...
warning: failed to remove docs/doxygenHTML/tabs.css: Permission denied
warning: failed to remove docs/doxygenHTML/functions_u.html: Permission denied
warning: failed to remove docs/doxygenHTML/classasyn_float64_array_client.html: Permission denied
Error: Invalid status code: 1
at ChildProcess.<anonymous> (/home/runner/work/_actions/sphinx-notes/pages/v2/main.js:9:19)
at ChildProcess.emit (events.js:314:20)
at maybeClose (internal/child_process.js:1022:16)
at Process.ChildProcess._handle.onexit (internal/child_process.js:287:5) {
code: 1
}
Error: Invalid status code: 1
at ChildProcess.<anonymous> (/home/runner/work/_actions/sphinx-notes/pages/v2/main.js:9:19)
at ChildProcess.emit (events.js:314:20)
at maybeClose (internal/child_process.js:1022:16)
at Process.ChildProcess._handle.onexit (internal/child_process.js:287:5)
Any idea why the Sphinx job is trying to delete those files?
Hi again. I'm raising this issue now to kinda timestamp when I noticed the build failures.
I'm using this action on multiple repos and specifying @v1
. but as of today it started failing to execute; even the workflows' run logs are not showing any output (just the very long cmd that was executed). Additionally (to be sure this isn't on me), I went back to an older successful workflow run and manually re-ran it; what was once successful is now failing. I'm hoping you have more insight. And to be absolutely sure, I checked doxygen's output locally on my PC: doxygen builds the docs fine locally without any warnings or errors.
release: https://github.com/doxygen/doxygen/releases/tag/Release_1_9_2
So are we considering upgrading to the new version?
A declarative, efficient, and flexible JavaScript library for building user interfaces.
๐ Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. ๐๐๐
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google โค๏ธ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.