action.yml

name: 'Generate and Commit Docs'

inputs:
  source-path:
    description: 'Source path containing the .h files'
    required: true
  target-path:
    description: 'Target path or file for the markdown documentation'
    required: true
  exclude-pattern:
    description: 'Pattern for excluding files (e.g. "*/test/*")'
  include-cpp:
    description: 'Include .cpp files'
    default: 'false'
  access-level:
    description: 'The minimum access level to be considered in the documentation'
    default: 'public'
  show-access-modifiers:
    description: 'Show access modifiers in the documentation'
    default: 'false'
  fail-on-warnings:
    description: 'Fail when documentation warnings are issued.'
    default: 'false'
  commit:
    description: 'Boolean flag to indicate whether to commit changes'
    default: 'true'
  commit-message:
    description: 'Commit message'
    default: 'Update documentation'
  committer-name:
    description: 'Username to use as author of the commit.'
    default: 'github-actions[bot]'
  committer-email:
    description: 'Email address to use as author of the commit.'
    default: '41898282+github-actions[bot]@users.noreply.github.com'
  debug:
    description: 'Enable debugging mode to provide additional output'
    default: 'false'

runs:
  using: "composite"

  steps:
  - name: Install doxygen dependencies
    shell: bash
    run: |
      # Import LLVM GPG key without using apt-key
      wget -q -O - https://apt.llvm.org/llvm-snapshot.gpg.key | gpg --dearmor -o /usr/share/keyrings/llvm-archive-keyring.gpg

      # Add the LLVM repository with the GPG keyring
      echo "deb [signed-by=/usr/share/keyrings/llvm-archive-keyring.gpg] http://apt.llvm.org/jammy/ llvm-toolchain-jammy-15 main" | sudo tee /etc/apt/sources.list.d/llvm.list > /dev/null
      
      # Update the package lists
      sudo apt-get -qq update

      # Install libclang and other necessary packages
      sudo apt-get install -y libclang1-15 libclang-cpp15

  - name: Set up Node.js
    uses: actions/setup-node@v4
    with:
      node-version: 20
      
  - name: Install render-docs
    shell: bash
    run: npm install github:arduino/render-docs#v1.0.0 --no-save

  - name: Cache Doxygen binaries
    id: cache-doxygen-binaries
    uses: actions/cache@v4
    with:
      path: |
        node_modules/doxygen/dist
      key: ${{ runner.os }}-doxygen-binaries-${{ hashFiles('node_modules/doxygen/lib/constants.js') }}

  - name: Run Docs Generation
    shell: bash
    run: |
      npx render-docs \
        ${{ inputs.source-path }} \
        ${{ inputs.target-path }} \
        ${{ inputs.exclude-pattern && format('--exclude "{0}"', inputs.exclude-pattern) || '' }} \
        ${{ inputs.include-cpp == 'true' && '--include-cpp' || '' }} \
        ${{ inputs.show-access-modifiers == 'true' && '--show-access-modifiers' || '' }} \
        ${{ inputs.access-level && format('--access-level {0}', inputs.access-level) || '' }} \
        ${{ inputs.fail-on-warnings == 'true' && '--fail-on-warnings' || '' }} \
        ${{ inputs.debug == 'true' && '--debug ' || '' }}

  - name: Commit Docs
    if: inputs.commit
    uses: EndBug/add-and-commit@v9
    with:
      add: "${{ inputs.target-path }}"
      author_name: "${{ inputs.committer-name }}"
      author_email: "${{ inputs.committer-email }}"
      message: "${{ inputs.commit-message }}"