Update Actions to generate and deploy documentation from master branch #737
Conversation
hopefully this will allow actions to generate and store HTML so that we can get it out of the repo
| @@ -13,14 +13,30 @@ jobs: | |||
| - name: apt-update | |||
| run: sudo apt-get update -qq | |||
| - name: apt-get doxygen | |||
| run: sudo apt-get install -y doxygen | |||
| - name: build doc | |||
| run: sudo apt-get install -y doxygen graphviz | |||
There was a problem hiding this comment.
Where is graphviz being used?
There was a problem hiding this comment.
graphviz is the project that creates the DOT graphing engines which doxygen will call to produce code graphs. See here for an example. The use of DOT is default for doxygen, but can be disabled in the Doxyfile. I personally, always like to have the graphs.
| - name: Upload static files as artifact | ||
| id: deployment | ||
| uses: actions/upload-pages-artifact@v3 # or specific "vX.X.X" version tag for this action |
There was a problem hiding this comment.
Looks like some of this was copied from the docs at https://github.com/actions/upload-pages-artifact
Any reason to move away from actions-gh-pages?
There was a problem hiding this comment.
gh-pages requires that a branch be created specifically to hold generated artifacts. That is, the HTML site that gets generated now needs to be committed to the repo; which (IMHO) defeats one of the major purposes of automated documentation generation.
This PR removes the dependency on a specific branch and generates the content straight from master as an artifact that github handles itself. Thus, no repo storage of an output artifact. Which can help to prevent issues where the output artifact gets out of sync with the source.
There was a problem hiding this comment.
and yes. I used the https://github.com/actions/upload-pages-artifact as a reference for this update.
There was a problem hiding this comment.
Globally I'm ok with the solution, which means no need for a specific gh-pages branch anymore.
But also no immediate way to see the public pages have been updated unless checking deployment jobs. Until now that commit to gh-pages was a clear indicator.
I'm ok with it, though.
There was a problem hiding this comment.
With the make file, we can set the standard build job to also make docs, then produce warnings or errors on documentation. That way the build or PR check fails
There was a problem hiding this comment.
I'm not sure I want PR to be blocked by documentation generation errors either. Just trying to find a way to get into automation (which is good) without loosing automated information :)
There was a problem hiding this comment.
Honest question. Why not enforce documentation?
In the least, it's a single line.
There was a problem hiding this comment.
Documentation building failures should not block someone from contributing to the project. But that's just like my opinion, man.
based on the great work of @riri in PR #734 . i have taken things 1 step further and updated the actions to allow generation of documentation directly from the master branch. Not only does it generate from the master branch; it also does so without the need to store any HTML in the repo. no separate branches or anything.
The way it works is by github actions allowing the upload of artifacts. So, on push, the action builds the code, then builds the documentation, then uploads the html directory as an artifact.
Then the deployment action grabs the artifact and deploys that as a webpage. You can view the web page example on my repo linked here
CRITICAL: the build and deployment settings for the repo will need to be updated from source = branch to source = github action
Note: i also took a moment to fix the errors around building DOT diagrams.