Doxygen second pass: coverage, improvements, fixes, etc. #142
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,177 @@ | ||
| name: Generate docs | ||
| permissions: | ||
| contents: read | ||
|
|
||
| # Generates Doxygen docs and uploads them as a workflow artifact. | ||
|
|
||
| # This workflow is used to validate documentation before merge, for example catching | ||
| # things like broken @ref tags, missing @param tags, etc. | ||
|
|
||
| # The artifact is attached to the workflow run so reviewers can download a preview, | ||
| # but also to verify the documentation artifact is valid for subsequent release runs | ||
| # that will publish them to the LiveKit docs web page: https://docs.livekit.io/reference/client-sdk-cpp/ | ||
| on: | ||
| pull_request: | ||
| branches: ["main"] | ||
| paths: | ||
| - include/** | ||
| - src/** | ||
| - docs/** | ||
| - scripts/generate-docs.sh | ||
| - .github/workflows/generate-docs.yml | ||
| - .github/workflows/publish-docs.yml | ||
| workflow_call: | ||
| inputs: | ||
| version: | ||
| description: 'Documentation version (e.g. v0.1.0)' | ||
| required: false | ||
| type: string | ||
| upload_artifact: | ||
| description: 'Upload the generated docs folder as a workflow artifact' | ||
| required: false | ||
| type: boolean | ||
| default: true | ||
| artifact_name: | ||
| description: 'Name to use for the uploaded docs artifact' | ||
| required: false | ||
| type: string | ||
| default: livekit-cpp-docs | ||
| artifact_retention_days: | ||
| description: 'Retention (days) for the uploaded docs artifact' | ||
| required: false | ||
| type: number | ||
| default: 7 | ||
| outputs: | ||
| project_number: | ||
| description: 'Doxygen PROJECT_NUMBER used for the build (e.g., v1.2.3)' | ||
| value: ${{ jobs.validate.outputs.project_number }} | ||
| artifact_name: | ||
| description: 'Name of the uploaded docs artifact (empty if upload was skipped via upload_artifact: false)' | ||
| value: ${{ jobs.validate.outputs.artifact_name }} | ||
|
|
||
| jobs: | ||
| validate: | ||
| name: Generate and verify docs | ||
| runs-on: ubuntu-latest | ||
| outputs: | ||
| project_number: ${{ steps.build_docs.outputs.project_number }} | ||
| artifact_name: ${{ steps.artifact_meta.outputs.name }} | ||
| steps: | ||
| - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 | ||
| with: | ||
| # fetch-depth: 0 is required so `git describe --tags` in | ||
| # scripts/generate-docs.sh resolves the right version from the git history. | ||
| fetch-depth: 0 | ||
|
|
||
| # Doxygen is available on ubuntu-latest, but we install explicitly for stability | ||
| - name: Install Doxygen | ||
| run: | | ||
| sudo apt-get update | ||
| sudo apt-get install -y doxygen graphviz | ||
|
|
||
| - name: Generate docs (Doxygen) | ||
| id: build_docs | ||
| shell: bash | ||
| env: | ||
| INPUT_VERSION: ${{ inputs.version || '' }} | ||
| run: | | ||
| set -euo pipefail | ||
|
|
||
| args=() | ||
| if [[ -n "$INPUT_VERSION" ]]; then | ||
| args+=(--version "$INPUT_VERSION") | ||
| elif [[ "${{ github.ref_type }}" == "tag" ]]; then | ||
| args+=(--version "${{ github.ref_name }}") | ||
| fi | ||
|
|
||
| ./scripts/generate-docs.sh "${args[@]}" | ||
|
|
||
| - name: Print docs version | ||
| shell: bash | ||
| run: | | ||
| set -euo pipefail | ||
|
|
||
| PROJECT_NUMBER="${{ steps.build_docs.outputs.project_number }}" | ||
|
|
||
| if [[ -z "$PROJECT_NUMBER" ]]; then | ||
| echo "ERROR: build_docs step did not emit a project_number output." | ||
| exit 1 | ||
| fi | ||
|
|
||
| echo "Docs version: ${PROJECT_NUMBER}" | ||
|
|
||
| { | ||
| echo "Docs version: \`${PROJECT_NUMBER}\`" | ||
| echo "" | ||
| echo "> Note: On a non-tag/release run, the version will resolve to:" | ||
| echo " \`<closest tag>-<commits since tag>-<commit sha>\`" | ||
| } >>"$GITHUB_STEP_SUMMARY" | ||
|
|
||
| - name: Verify docs were generated | ||
| shell: bash | ||
| run: | | ||
| set -euo pipefail | ||
| if [[ ! -f docs/doxygen/html/index.html ]]; then | ||
| echo "ERROR: Expected docs at docs/doxygen/html/index.html but file not found." | ||
| exit 1 | ||
| fi | ||
|
|
||
| # `inputs.*` is only populated on `workflow_call`. On a direct | ||
| # `pull_request` trigger every `inputs.*` lookup is the empty string, so | ||
| # we OR-fold to the documented defaults to keep PR runs behaving the same | ||
| # as the workflow_call default of `upload_artifact: true`. | ||
| - name: Resolve artifact metadata | ||
| id: artifact_meta | ||
| if: inputs.upload_artifact || github.event_name == 'pull_request' | ||
| shell: bash | ||
| env: | ||
| INPUT_NAME: ${{ inputs.artifact_name || 'livekit-cpp-docs' }} | ||
| INPUT_RETENTION: ${{ inputs.artifact_retention_days || '7' }} | ||
| run: | | ||
| set -euo pipefail | ||
| if [[ -z "$INPUT_NAME" ]]; then | ||
| echo "ERROR: artifact name resolved to empty." | ||
| exit 1 | ||
| fi | ||
| echo "name=${INPUT_NAME}" >>"$GITHUB_OUTPUT" | ||
| echo "retention=${INPUT_RETENTION}" >>"$GITHUB_OUTPUT" | ||
|
|
||
| - name: Upload docs artifact | ||
| if: steps.artifact_meta.outputs.name != '' | ||
| uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1 | ||
| with: | ||
| name: ${{ steps.artifact_meta.outputs.name }} | ||
| path: docs/doxygen/html/ | ||
| retention-days: ${{ steps.artifact_meta.outputs.retention }} | ||
| if-no-files-found: error | ||
|
|
||
| # Simple check to make sure the documentation artifact is valid. | ||
| - name: Re-download artifact (publish workflow pre-validation) | ||
| if: steps.artifact_meta.outputs.name != '' | ||
| uses: actions/download-artifact@37930b1c2abaa49bbe596cd826c3c89aef350131 # v7.0.0 | ||
| with: | ||
| name: ${{ steps.artifact_meta.outputs.name }} | ||
| path: html | ||
|
|
||
| - name: Inspect downloaded artifact | ||
| if: steps.artifact_meta.outputs.name != '' | ||
| shell: bash | ||
| run: | | ||
| set -euo pipefail | ||
|
|
||
| NAME="${{ steps.artifact_meta.outputs.name }}" | ||
| ROOT="html" | ||
|
|
||
| echo "Artifact '${NAME}' extracted into '${ROOT}/'. Top-level contents:" | ||
| # `sed -n '1,Np'` reads the whole pipe before truncating its output, | ||
| # so the producer (ls) never hits SIGPIPE under `pipefail`. | ||
| ls -la "$ROOT" | sed -n '1,40p' | ||
|
|
||
| TOTAL=$(find "$ROOT" -type f | wc -l | tr -d ' ') | ||
| echo "Total files: ${TOTAL}" | ||
|
|
||
| if [[ ! -f "${ROOT}/index.html" ]]; then | ||
| echo "ERROR: ${ROOT}/index.html is missing -- artifact layout regressed." | ||
| echo " publish-docs.yml expects html/index.html." | ||
| exit 1 | ||
| fi |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
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.
run_id==commit hash? if not we should consider using commit hash
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.
Nope, this is the integer incrementing count (see actions tab). Just needs to be unique such that if for some reason two releases are pushing docs (say we back-patched an old tag in addition to a new one simultaneously), they wouldn't conflict.
This is just the temporary artifact name between the generate and publish stages in the actions space, not in S3 or anywhere permanent. Open to SHA if you prefer
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.
up to you, sha might be easier to track if we need to. not sure if thats a real use case or not