Update Actions to generate and deploy documentation from master branch #737
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -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 graphviz | ||
| - name: build docs | ||
| run: make docs | ||
| - name: Upload static files as artifact | ||
| id: deployment | ||
| uses: actions/upload-pages-artifact@v3 # or specific "vX.X.X" version tag for this action | ||
|
Comment on lines
+19
to
+21
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 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 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. |
||
| with: | ||
| path: docs/html/ | ||
|
|
||
| # Deployment job | ||
| deploy: | ||
| environment: | ||
| name: github-pages | ||
| url: ${{ steps.deployment.outputs.page_url }} | ||
| runs-on: ubuntu-latest | ||
| needs: build-documentation | ||
| # Grant GITHUB_TOKEN the permissions required to make a Pages deployment | ||
| permissions: | ||
| pages: write # to deploy to Pages | ||
| id-token: write # to verify the deployment originates from an appropriate source | ||
| steps: | ||
| - name: Deploy to GitHub Pages | ||
| id: deployment | ||
| uses: actions/deploy-pages@v4 | ||
|
|
||
|
|
||
|
|
||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Where is graphviz being used?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.