Introduction

We're happy to announce the beta of hdoc's integration with GitHub Actions. This makes it possible to integrate hdoc into your existing GitHub Actions CI workflow, generate C++ documentation for your project, and upload it to the internet where you can share it with others, all for free.

We're always looking for ways to make adding great documentation to your C++ project possible. Until now, users had to manually run the hdoc tool over their code to generate documentation and push it to our public documentation hosting service: docs.hdoc.io.

Alternatively, users had to compile hdoc from our open source repo, run hdoc over their code, and then upload the documentation to their own servers to make it accessible to others. Some users integrated these workflows with their CI solutions, which made things even more complicated. Now, there were docker containers to contend with, CI YAML files to write, and even more code to maintain.

Getting started with the new GitHub Action

Today, we're providing a first-party solution that allows GitHub users to seamlessly add hdoc to their GitHub Actions CI workflow. With the new integration, users no longer have to download anything to use hdoc, and they can now have documentation generated on every commit and publicly available via our CDN — all for free. Here's how it works:

• Create an account on hdoc.io if you don't already have one.
• Create a project and save the API key that appears during the project creation process.
• Add the API key as an Encrypted secret in the GitHub repository you want to use the GitHub Action on.
• Modify your GitHub Action workflow file to add the hdoc GitHub Action.

Adding hdoc to your existing GitHub Action workflow is a matter of a few lines of code. The workflow file below is an example of how you might build a C++ project with GitHub Actions, without autogenerated documentation:

name: example-project

# Triggers the workflow on push or pull request events but only for the main branch
on:
  push:
    branches: [ main ]

# A simple workflow to build a C++ project
jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v2

      - name: Install dependencies, then configure and build project
        run: |
          cmake -GNinja -Bbuild -DCMAKE_EXPORT_COMPILE_COMMANDS=1
          ninja -C build

To enable hdoc, modify the workflow file as follows:

name: example-project

# Triggers the workflow on push or pull request events but only for the main branch
on:
  push:
    branches: [ main ]

# A simple workflow to build a C++ project and generate documentation with hdoc
jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v2

      - name: Install dependencies, then configure and build project
        run: |
          sudo apt install build-essential cmake ninja-build
          cmake -GNinja -Bbuild -DCMAKE_EXPORT_COMPILE_COMMANDS=1
          ninja -C build

      # New workflow step that runs hdoc and uploads documentation to docs.hdoc.io
      - name: Run hdoc to generate documentation and push it to docs.hdoc.io
        uses: hdoc/hdoc-github-action@v2
        with:
          compile-commands-path: build/compile_commands.json
          hdoc-api-key: ${{ secrets.HDOC_PROJECT_API_KEY }}

The resulting workflow will accomplish the following:

• Install dependencies
• Configure your project to be built with CMake and generate a compile_commands.json file
• Build your project
• hdoc will run over your project, generate documentation, and push it to docs.hdoc.io where it will be publicly accessible

More detailed instructions can be found at the hdoc-github-action GitHub repo.

Beta status

We have tested the action with several public projects that already using GitHub Actions for their CI, but due to the complexity inherent in GitHub Actions we are not yet fully confident that it will work in all situations. We hope that you, the user, will try out this service and report back if there are any problems so we can fix them. Please file an issue in the hdoc-github-action GitHub repository if you encounter any problems.